/ Hex Artifact Content
Login

Artifact c0e84a2d6e9f3263599174ff7261ba6daf730b4f:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 39 34 20 32 30 30 38 2f 30  n,v 1.394 2008/0
05f0: 38 2f 32 35 20 32 31 3a 32 33 3a 30 32 20 64 72  8/25 21:23:02 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c  .** Add the abil
0750: 69 74 79 20 74 6f 20 6d 61 72 6b 20 69 6e 74 65  ity to mark inte
0760: 72 66 61 63 65 73 20 61 73 20 64 65 70 72 65 63  rfaces as deprec
0770: 61 74 65 64 2e 0a 2a 2f 0a 23 69 66 20 28 5f 5f  ated..*/.#if (__
0780: 47 4e 55 43 5f 5f 20 3e 20 33 20 7c 7c 20 28 5f  GNUC__ > 3 || (_
0790: 5f 47 4e 55 43 5f 5f 20 3d 3d 20 33 20 26 26 20  _GNUC__ == 3 && 
07a0: 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f 5f 20 3e  __GNUC_MINOR__ >
07b0: 3d 20 31 29 29 0a 20 20 2f 2a 20 47 43 43 20 61  = 1)).  /* GCC a
07c0: 64 64 65 64 20 74 68 65 20 64 65 70 72 65 63 61  dded the depreca
07d0: 74 65 64 20 61 74 74 72 69 62 75 74 65 20 69 6e  ted attribute in
07e0: 20 76 65 72 73 69 6f 6e 20 33 2e 31 20 2a 2f 0a   version 3.1 */.
07f0: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
0800: 5f 44 45 50 52 45 43 41 54 45 44 20 5f 5f 61 74  _DEPRECATED __at
0810: 74 72 69 62 75 74 65 5f 5f 20 28 28 64 65 70 72  tribute__ ((depr
0820: 65 63 61 74 65 64 29 29 0a 23 65 6c 69 66 20 64  ecated)).#elif d
0830: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
0840: 0a 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54  .  #define SQLIT
0850: 45 5f 44 45 50 52 45 43 41 54 45 44 20 5f 5f 64  E_DEPRECATED __d
0860: 65 63 6c 73 70 65 63 28 64 65 70 72 65 63 61 74  eclspec(deprecat
0870: 65 64 29 0a 23 65 6c 73 65 0a 20 20 23 64 65 66  ed).#else.  #def
0880: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
0890: 43 41 54 45 44 0a 23 65 6e 64 69 66 0a 0a 2f 2a  CATED.#endif../*
08a0: 0a 2a 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c  .** Add the abil
08b0: 69 74 79 20 74 6f 20 6d 61 72 6b 20 69 6e 74 65  ity to mark inte
08c0: 72 66 61 63 65 73 20 61 73 20 65 78 70 65 72 69  rfaces as experi
08d0: 6d 65 6e 74 61 6c 2e 0a 2a 2f 0a 23 69 66 20 28  mental..*/.#if (
08e0: 5f 5f 47 4e 55 43 5f 5f 20 3e 20 34 20 7c 7c 20  __GNUC__ > 4 || 
08f0: 28 5f 5f 47 4e 55 43 5f 5f 20 3d 3d 20 34 20 26  (__GNUC__ == 4 &
0900: 26 20 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f 5f  & __GNUC_MINOR__
0910: 20 3e 3d 20 33 29 29 0a 20 20 2f 2a 20 49 20 63   >= 3)).  /* I c
0920: 61 6e 20 63 6f 6e 66 69 72 6d 20 74 68 61 74 20  an confirm that 
0930: 69 74 20 64 6f 65 73 20 6e 6f 74 20 77 6f 72 6b  it does not work
0940: 20 6f 6e 20 76 65 72 73 69 6f 6e 20 34 2e 31 2e   on version 4.1.
0950: 30 2e 2e 2e 20 2a 2f 0a 20 20 2f 2a 20 46 69 72  0... */.  /* Fir
0960: 73 74 20 61 70 70 65 61 72 73 20 69 6e 20 47 43  st appears in GC
0970: 43 20 64 6f 63 73 20 66 6f 72 20 76 65 72 73 69  C docs for versi
0980: 6f 6e 20 34 2e 33 2e 30 20 2a 2f 0a 20 20 23 64  on 4.3.0 */.  #d
0990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50  efine SQLITE_EXP
09a0: 45 52 49 4d 45 4e 54 41 4c 20 5f 5f 61 74 74 72  ERIMENTAL __attr
09b0: 69 62 75 74 65 5f 5f 20 28 28 77 61 72 6e 69 6e  ibute__ ((warnin
09c0: 67 20 28 22 69 73 20 65 78 70 65 72 69 6d 65 6e  g ("is experimen
09d0: 74 61 6c 22 29 29 29 0a 23 65 6c 69 66 20 64 65  tal"))).#elif de
09e0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a  fined(_MSC_VER).
09f0: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
0a00: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 5f 5f  _EXPERIMENTAL __
0a10: 64 65 63 6c 73 70 65 63 28 64 65 70 72 65 63 61  declspec(depreca
0a20: 74 65 64 28 22 77 61 73 20 64 65 63 6c 61 72 65  ted("was declare
0a30: 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 29  d experimental")
0a40: 29 0a 23 65 6c 73 65 0a 20 20 23 64 65 66 69 6e  ).#else.  #defin
0a50: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0a60: 45 4e 54 41 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ENTAL.#endif../*
0a70: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0a80: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0a90: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0aa0: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0ab0: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0ac0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0ad0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0ae0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0af0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0b00: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0b10: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0b20: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0b30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0b40: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0b50: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0b60: 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 7d 20  umbers {H10010} 
0b70: 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60100>.**.** T
0b80: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0b90: 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52  N and SQLITE_VER
0ba0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66  SION_NUMBER #def
0bb0: 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73  ines in.** the s
0bc0: 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70  qlite3.h file sp
0bd0: 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f  ecify the versio
0be0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68  n of SQLite with
0bf0: 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68   which.** that h
0c00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0c10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0c20: 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66  The "version" of
0c30: 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72   SQLite is a str
0c40: 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ing of the form 
0c50: 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20  "X.Y.Z"..** The 
0c60: 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f  phrase "alpha" o
0c70: 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62  r "beta" might b
0c80: 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72  e appended after
0c90: 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58   the Z..** The X
0ca0: 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20   value is major 
0cb0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0cc0: 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74  lways 3 in SQLit
0cd0: 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c  e3..** The X val
0ce0: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ue only changes 
0cf0: 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63  when backwards c
0d00: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
0d10: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
0d20: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0d30: 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73   break backwards
0d40: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
0d50: 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69  ** The Y value i
0d60: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
0d70: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f  ion number and o
0d80: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0d90: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61  .** there are ma
0da0: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61  jor feature enha
0db0: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  ncements that ar
0dc0: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61  e forwards compa
0dd0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74  tible.** but not
0de0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0df0: 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20  tible..** The Z 
0e00: 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c  value is the rel
0e10: 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20  ease number and 
0e20: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77  is incremented w
0e30: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65  ith.** each rele
0e40: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62  ase but resets b
0e50: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65  ack to 0 wheneve
0e60: 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  r Y is increment
0e70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
0e80: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
0e90: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
0ea0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0eb0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a  on_number()]..**
0ec0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
0ed0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54  **.** {H10011} T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0ef0: 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65  N #define in the
0f00: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
0f10: 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20  r file shall.** 
0f20: 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74           evaluat
0f30: 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  e to a string li
0f40: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
0f50: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
0f60: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0f70: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64  h which the head
0f80: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
0f90: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  iated..**.** {H1
0fa0: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45  0014} The SQLITE
0fb0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0fc0: 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 72 65  #define shall re
0fd0: 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e 74 65  solve to an inte
0fe0: 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
0ff0: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28  with the value (
1000: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
1010: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
1020: 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20   Y, and Z.**    
1030: 20 20 20 20 20 20 61 72 65 20 74 68 65 20 6d 61        are the ma
1040: 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e  jor version, min
1050: 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20  or version, and 
1060: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a  release number..
1070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1080: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
1090: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
10a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
10b0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45  ION_NUMBER  --VE
10c0: 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a  RSION-NUMBER--..
10d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10e0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
10f0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1100: 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30   {H10020} <S6010
1110: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1120: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a  sqlite3_version.
1130: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74  **.** These feat
1140: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  ures provide the
1150: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1160: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1170: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64  _VERSION].** and
1180: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1190: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65  _NUMBER] #define
11a0: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c  s in the header,
11b0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
11c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
11d0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11e0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11f0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72  le.  Cautious pr
1200: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a  ogrammers might.
1210: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65  ** include a che
1220: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ck in their appl
1230: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66  ication to verif
1240: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65  y that.** sqlite
1250: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1260: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74  ber() always ret
1270: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
1280: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
1290: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a  N_NUMBER]..**.**
12a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
12b0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
12c0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
12d0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
12e0: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
12f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1300: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1310: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1320: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1330: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1340: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1350: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1360: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
1370: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
1380: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1390: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  the DLL..**.** I
13a0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
13b0: 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73   {H10021} The [s
13c0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
13d0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65  n_number()] inte
13e0: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
13f0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rn.**          a
1400: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1410: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  to [SQLITE_VERSI
1420: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a  ON_NUMBER]..**.*
1430: 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b  * {H10022} The [
1440: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d  sqlite3_version]
1450: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1460: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a   shall contain.*
1470: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
1480: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
1490: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
14a0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  ng..**.** {H1002
14b0: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
14c0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75  libversion()] fu
14d0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
14e0: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
14f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1500: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
1510: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
1520: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
1530: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
1540: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1550: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1560: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1570: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1580: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1590: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
15a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
15b0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
15c0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
15d0: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d  eadsafe {H10100}
15e0: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60100>.**.** 
15f0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1600: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1610: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1620: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1630: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1640: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1650: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d  macro is true, m
1660: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1670: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1680: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1690: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f   When that macro
16a0: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68   is false,.** th
16b0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
16c0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
16d0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
16e0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
16f0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1700: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1710: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1720: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1730: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1740: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1750: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1760: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1770: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1780: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1790: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
17a0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
17b0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
17c0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
17d0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
17e0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
17f0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1800: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
1810: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
1820: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1830: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1840: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
1850: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
1860: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
1870: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1880: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1890: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
18a0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
18b0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
18c0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
18d0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
18e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
18f0: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
1900: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
1910: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
1920: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
1930: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1940: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
1950: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
1960: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
1970: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20  READSAFE=1 then 
1980: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
1990: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
19a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
19b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
19c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
19d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
19e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
19f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
1a00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1a10: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
1a20: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1a30: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
1a40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1a50: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72  TEX].  The retur
1a60: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1a70: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a  function shows.*
1a80: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75  * only the defau
1a90: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  lt compile-time 
1aa0: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79  setting, not any
1ab0: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
1ac0: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74  s.** to that set
1ad0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ting..**.** INVA
1ae0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1af0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  10101} The [sqli
1b00: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1b10: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
1b20: 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20   return nonzero 
1b30: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
1b40: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1b50: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20  ed with the its 
1b60: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20  mutexes enabled 
1b70: 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  by default.**   
1b80: 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f 20 69         or zero i
1b90: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1ba0: 70 69 6c 65 64 20 73 75 63 68 20 74 68 61 74 20  piled such that 
1bb0: 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 20  mutexes are.**  
1bc0: 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e 65 6e          permanen
1bd0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  tly disabled..**
1be0: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65  .** {H10102} The
1bf0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c00: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
1c10: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75  threadsafe()] fu
1c20: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
1c30: 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61     shall not cha
1c40: 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73  nge when mutex s
1c50: 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66  etting are modif
1c60: 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20  ied at.**       
1c70: 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67     runtime using
1c80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1c90: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
1ca0: 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  e and .**       
1cb0: 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68     especially th
1cc0: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
1cd0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a  _SINGLETHREAD],.
1ce0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1cf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1d00: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1d10: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
1d20: 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ED],.**         
1d30: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
1d40: 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73  FIG_MUTEX] verbs
1d50: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d60: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1d70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d80: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1d90: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1da0: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1db0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1dc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dd0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1de0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1df0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1e00: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1e10: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1e20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1e30: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1e40: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1e50: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1e60: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1e70: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1e80: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1e90: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1ea0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1eb0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1ec0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1ed0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1ee0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1ef0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1f00: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1f10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1f20: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1f30: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1f40: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1f50: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1f60: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f70: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1f80: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1f90: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1fa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1fb0: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1fc0: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1fd0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1fe0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1ff0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2000: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2010: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2020: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
2030: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
2040: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
2050: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
2060: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
2070: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
2080: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
2090: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
20a0: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
20b0: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
20c0: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
20d0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
20e0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
20f0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
2100: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
2110: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
2120: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
2130: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
2140: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
2150: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
2160: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
2170: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
2180: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
2190: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
21a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
21b0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nly..**.** INVAR
21c0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
21d0: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0201} The [sqlit
21e0: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  e_int64] and [sq
21f0: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70  lite3_int64] typ
2200: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
2210: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
2220: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2230: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ger..**.** {H102
2240: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
2250: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
2260: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
2270: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
2280: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
2290: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
22a0: 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66  teger..*/.#ifdef
22b0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
22c0: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
22d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
22e0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
22f0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2310: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2320: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
2330: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
2340: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
2350: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
2360: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2370: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2380: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2390: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
23a0: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
23b0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
23c0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
23d0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
23e0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
23f0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2400: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
2410: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
2420: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
2430: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
2440: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
2450: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
2460: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2470: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2480: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2490: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
24a0: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
24b0: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
24c0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
24d0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
24e0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
24f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2500: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2510: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2520: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2530: 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30  on {H12010} <S30
2540: 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  100><S40200>.**.
2550: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2560: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
2570: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
2580: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  e3] object..**.*
2590: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
25a0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
25b0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
25c0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
25d0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
25e0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
25f0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
2600: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
2610: 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  les] associated 
2620: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  with.** the [sql
2630: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2640: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2650: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2660: 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ject..** The [sq
2670: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2680: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2690: 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61   be used to loca
26a0: 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61  te all.** [prepa
26b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
26c0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
26d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
26e0: 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72  ection] if desir
26f0: 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63  ed..** Typical c
2700: 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c  ode might look l
2710: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
2720: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2730: 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  >.** sqlite3_stm
2740: 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69  t *pStmt;.** whi
2750: 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c  le( (pStmt = sql
2760: 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64  ite3_next_stmt(d
2770: 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20  b, 0))!=0 ){.** 
2780: 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33  &nbsp;   sqlite3
2790: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29  _finalize(pStmt)
27a0: 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e  ;.** }.** </pre>
27b0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
27c0: 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
27d0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
27e0: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
27f0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2800: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2810: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2820: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2830: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2840: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  TS:.**.** {H1201
2850: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
2860: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2870: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c  _close(C)] shall
2880: 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
2890: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
28a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
28b0: 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b  bject C..**.** {
28c0: 48 31 32 30 31 32 7d 20 41 20 73 75 63 63 65 73  H12012} A succes
28d0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
28e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
28f0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c  shall return SQL
2900: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
2910: 31 32 30 31 33 7d 20 41 20 73 75 63 63 65 73 73  12013} A success
2920: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2930: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2940: 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c  hall release all
2950: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2960: 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72  ory and system r
2970: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
2980: 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61  ted with [databa
2990: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
29a0: 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a  *          C..**
29b0: 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63  .** {H12014} A c
29c0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29d0: 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b  close(C)] on a [
29e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29f0: 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20  ion] C that.**  
2a00: 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20          has one 
2a10: 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72  or more open [pr
2a20: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a30: 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  s] shall fail wi
2a40: 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2a50: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2a60: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  error code..**.*
2a70: 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c  * {H12015} A cal
2a80: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2a90: 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20 43 20  ose(C)] where C 
2aa0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2ab0: 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  r shall.**      
2ac0: 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54      return SQLIT
2ad0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  E_OK..**.** {H12
2ae0: 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  019} When [sqlit
2af0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20  e3_close(C)] is 
2b00: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61  invoked on a [da
2b10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b20: 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] C.**         
2b30: 20 74 68 61 74 20 68 61 73 20 61 20 70 65 6e 64   that has a pend
2b40: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  ing transaction,
2b50: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2b60: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
2b70: 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63        rolled bac
2b80: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  k..**.** ASSUMPT
2b90: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
2ba0: 30 31 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d  016} The C param
2bb0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2bc0: 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20  _close(C)] must 
2bd0: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
2be0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
2bf0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2c00: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
2c10: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
2c20: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
2c30: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2c40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2c50: 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2c60: 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
2c70: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
2c80: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
2c90: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2ca0: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2cb0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2cc0: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
2cd0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
2ce0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
2cf0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
2d00: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
2d10: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
2d20: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2d30: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2d40: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2d50: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2d60: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2d70: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2d80: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2d90: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2da0: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2db0: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2dc0: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2dd0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2de0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2df0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2e00: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2e10: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2e20: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
2e30: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
2e40: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
2e50: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
2e60: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
2e70: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2e80: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2e90: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2ea0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2eb0: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2ec0: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2ed0: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2ee0: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2ef0: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2f00: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2f10: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2f20: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2f30: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2f40: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2f50: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2f60: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2f70: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2f80: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2f90: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2fa0: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2fb0: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2fc0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2fd0: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2fe0: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2ff0: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
3000: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3010: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3020: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3030: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
3040: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
3050: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
3060: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
3070: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
3080: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
3090: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
30a0: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
30b0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
30c0: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
30d0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
30e0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
30f0: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
3100: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
3110: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
3120: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
3130: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
3140: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
3150: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
3160: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
3170: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
3180: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
3190: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
31a0: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
31b0: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
31c0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
31d0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
31e0: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
31f0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
3200: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3210: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
3220: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
3230: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
3240: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
3250: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3260: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3270: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
3280: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3290: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
32a0: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
32b0: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
32c0: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
32d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
32f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3300: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3310: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
3320: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
3330: 31 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  101} A successfu
3340: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
3350: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3360: 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20  S,C,A,E)].**    
3370: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75        shall sequ
3380: 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74  entially evaluat
3390: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
33a0: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20  -8 encoded,.**  
33b0: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f          semicolo
33c0: 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
33d0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
33e0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
33f0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  d.**          st
3400: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
3410: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
3420: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3430: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
3440: 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {H12102} If the 
3450: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
3460: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3470: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
3480: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3490: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
34a0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
34b0: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
34c0: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
34d0: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
34e0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
34f0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
3500: 48 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  H12104} The retu
3510: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
3520: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
3530: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
3540: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
3550: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
3560: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
3570: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
3580: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  letion..**.** {H
3590: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
35a0: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
35b0: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
35c0: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
35d0: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
35e0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
35f0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
3600: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
3610: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d  ..**.** {H12107}
3620: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
3630: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
3640: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
3650: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3660: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
3670: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
3680: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3690: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
36a0: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
36b0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
36c0: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
36d0: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
36e0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
36f0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
3700: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
3710: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
3720: 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66  *.** {H12110} If
3730: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3740: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3750: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3760: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3770: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3780: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3790: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
37a0: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
37b0: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
37c0: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
37d0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
37e0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
37f0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
3800: 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65  .** {H12113} The
3810: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3820: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3830: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3840: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3850: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3860: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3870: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3880: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20  .**.** {H12116} 
3890: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
38a0: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
38b0: 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64 20 70  ll set the 2nd p
38c0: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
38d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
38e0: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
38f0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3900: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
3910: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
3920: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
3930: 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {H12119} The [s
3940: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3950: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3960: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3970: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3980: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3990: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
39a0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
39b0: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
39c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
39d0: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ues for each col
39e0: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
39f0: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f  nt result set ro
3a00: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  w as.**         
3a10: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
3a20: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3a30: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ext()]..**.** {H
3a40: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69  12122} The [sqli
3a50: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3a60: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3a70: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3a80: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3a90: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3aa0: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3ab0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3ac0: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
3ad0: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
3ae0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
3af0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
3b00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
3b10: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
3b20: 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68  * {H12125} If th
3b30: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3b40: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3b50: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
3b60: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3b70: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3b80: 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73  all silently dis
3b90: 63 61 72 64 20 71 75 65 72 79 20 72 65 73 75 6c  card query resul
3ba0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  ts..**.** {H1213
3bb0: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3bc0: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
3bd0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
3be0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
3c00: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53  tements in the S
3c10: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3c30: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a  C,A,E)] and if.*
3c40: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45  *          the E
3c50: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3c60: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71  t NULL, then [sq
3c70: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3c80: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20  all store.**    
3c90: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61        in *E an a
3ca0: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
3cb0: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e   message written
3cc0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
3cd0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
3ce0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
3cf0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
3d00: 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {H12134} The [s
3d10: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3d20: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20  C,A,E)] routine 
3d30: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61  shall set the va
3d40: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
3d50: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66     *E to NULL if
3d60: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61   E is not NULL a
3d70: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  nd there are no 
3d80: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  errors..**.** {H
3d90: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  12137} The [sqli
3da0: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3db0: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,E)] function sh
3dc0: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72  all set the [err
3dd0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  or code].**     
3de0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65       and message
3df0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
3e00: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
3e10: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3e20: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e30: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3e40: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
3e50: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66  *.** {H12138} If
3e60: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3e70: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3e80: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3e90: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20   NULL or an.**  
3ea0: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
3eb0: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73  ring or contains
3ec0: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
3ed0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20  han whitespace, 
3ee0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20  comments,.**    
3ef0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d        and/or sem
3f00: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65  icolons, then re
3f10: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65  sults of [sqlite
3f20: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3f30: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3f40: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3f50: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3f60: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
3f70: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74     shall reset t
3f80: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72  o indicate no er
3f90: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  rors..**.** ASSU
3fa0: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
3fb0: 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73  A12141} The firs
3fc0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
3fd0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3fe0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
3ff0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20   and open.**    
4000: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
4010: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
4020: 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20  ** {A12142} The 
4030: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4040: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
4050: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
4060: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
4070: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
4080: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ning..**.** {A12
4090: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
40a0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
40b0: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
40c0: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
40d0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
40e0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
40f0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
4100: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
4110: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
4120: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
4130: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
4140: 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65  .** {A12145} The
4150: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
4160: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
4170: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
4180: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
4190: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
41a0: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
41b0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
41c0: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
41d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
41e0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
41f0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
4200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4210: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
4220: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
4230: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4250: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
4260: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
4270: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4280: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4290: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
42a0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
42b0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
42c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42e0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
42f0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4300: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
4310: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
4340: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
4350: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4360: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
4370: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a  10210} <S10700>.
4380: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4390: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
43a0: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
43b0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
43c0: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
43d0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
43e0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
43f0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4400: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4410: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
4420: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4430: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4440: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
4450: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4460: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4470: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4480: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4490: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
44a0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
44b0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
44c0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
44d0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
44f0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
4500: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
4510: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
4520: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4540: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4550: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4560: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4570: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4580: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4590: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
45a0: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
45b0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
45d0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
45e0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
45f0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4600: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
4610: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
4620: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4630: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4640: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4650: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4660: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4670: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4680: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4690: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
46a0: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
46b0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
46c0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
46d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
46e0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
46f0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
4700: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4710: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
4720: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4730: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4740: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4760: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4770: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4780: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4790: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
47a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47b0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
47c0: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
47d0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
47e0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
47f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
4800: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
4810: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
4820: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4830: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4840: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4850: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
4860: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
4870: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
4880: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4890: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
48a0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
48b0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
48c0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
48d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48e0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
48f0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
4900: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4910: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4920: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4930: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
4940: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
4950: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
4960: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4970: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4980: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4990: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
49b0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
49c0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
49d0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
49f0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4a00: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4a10: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4a20: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4a30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4a40: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4a50: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
4a60: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a80: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a90: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4aa0: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4ab0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4ac0: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4ad0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4ae0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4af0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4b00: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4b10: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4b20: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4b30: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4b40: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4b50: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4b60: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b80: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b90: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4ba0: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4bb0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4bc0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4bd0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4be0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4bf0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4c00: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4c10: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4c20: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4c30: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4c40: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4c50: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4c60: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4c70: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4c80: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4c90: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4cb0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4cc0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4cd0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4ce0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4cf0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4d00: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4d10: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4d20: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
4d30: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
4d40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d50: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4d60: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4d70: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4d80: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4d90: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4da0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4db0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4dc0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4dd0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4de0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4df0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4e00: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4e10: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4e20: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4e30: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4e40: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4e50: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4e60: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4e70: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4e80: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4e90: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4ea0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4eb0: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4ec0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4ed0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4ee0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4ef0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4f00: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4f10: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4f20: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4f30: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4f40: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4f50: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4f60: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f70: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f80: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f90: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4fa0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4fb0: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4fc0: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fe0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4ff0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
5000: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
5010: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
5020: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
5030: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
5040: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
5050: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
5060: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
5070: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
5080: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
5090: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
50a0: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
50b0: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
50c0: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
50d0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
50e0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
50f0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
5100: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
5110: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
5120: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
5130: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
5140: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
5150: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
5160: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
5170: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
5180: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
5190: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20  .**.** {H10223} 
51a0: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
51b0: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
51c0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
51d0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  all contains.** 
51e0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74           a relat
51f0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ed primary resul
5200: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66  t code as a pref
5210: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  ix..**.** {H1022
5220: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  4} Primary resul
5230: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
5240: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  ll contain a sin
5250: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
5260: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35  r..**.** {H10225
5270: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
5280: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
5290: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f  ll contain two o
52a0: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61  r more "_" chara
52b0: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
52c0: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69  0226} The numeri
52d0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
52e0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
52f0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
5300: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
5310: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
5320: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
5330: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
5340: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
5350: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
5360: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
5370: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
5380: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5390: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
53a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53b0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
53c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
53d0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
53e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
53f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5400: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
5410: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5420: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5430: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5440: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5450: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5460: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5470: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5480: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5490: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
54a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
54d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54e0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
54f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5500: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
5510: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5520: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5550: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5560: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5580: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5590: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
55a0: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
55b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55c0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
55d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55e0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
55f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5600: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
5610: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5620: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5640: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5650: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5660: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5680: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5690: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
56a0: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
56b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
56c0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
56d0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
56e0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
56f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5700: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
5710: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5720: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 0a  ERR | (15<<8))..
5730: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5740: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
5750: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
5760: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
5770: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
5780: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5790: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
57a0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
57b0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
57c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
57d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
57e0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
57f0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5800: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
5810: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
5820: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
5830: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5840: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5850: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5860: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5870: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5880: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5890: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
58a0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
58b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
58c0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
58d0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
58e0: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
58f0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5900: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
5910: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5920: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5930: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
5940: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5950: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5960: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5970: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5980: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5990: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
59a0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
59b0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
59c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
59d0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
59e0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
59f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
5a00: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5a10: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
5a20: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
5a30: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
5a40: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
5a50: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
5a60: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5a70: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
5a80: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5a90: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5aa0: 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  08000.#define SQ
5ab0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
5ac0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
5ad0: 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  10000../*.** CAP
5ae0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5af0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
5b00: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
5b10: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
5b20: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
5b30: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5b40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5b50: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5b60: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5b70: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5b80: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5b90: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5ba0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5bb0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5bc0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5bd0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5be0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5bf0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5c00: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5c10: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5c20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5c30: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5c40: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
5c50: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
5c60: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
5c70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5c80: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5c90: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5ca0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5cb0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5cc0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5cd0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5ce0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5cf0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5d00: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5d10: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5d20: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5d30: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5d40: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5d50: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5d60: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5d70: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5d80: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5d90: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5da0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5db0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5dc0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5dd0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5de0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5df0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5e00: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5e10: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5e20: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5e30: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5e40: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5e50: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5e70: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
5e80: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
5e90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ea0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
5eb0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5ec0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ed0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
5ee0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5ef0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f00: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
5f10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5f20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
5f40: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
5f50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f60: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
5f70: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5f80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f90: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
5fa0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5fb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5fc0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
5fd0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5fe0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ff0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
6000: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6010: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6020: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
6030: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6040: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6050: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
6060: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
6070: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6080: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
6090: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
60a0: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
60b0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
60c0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
60d0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
60e0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
60f0: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
6100: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
6110: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
6120: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
6130: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6140: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6160: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
6170: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
6180: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
6190: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
61a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
61b0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
61c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
61d0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
61e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
61f0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
6200: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
6210: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
6220: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
6230: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
6240: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
6250: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6260: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6270: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6280: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6290: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
62a0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
62b0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
62c0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
62d0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
62e0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
62f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6300: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6310: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6320: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6330: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6340: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6350: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6360: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6370: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
6380: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
6390: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
63a0: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
63b0: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
63c0: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
63d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
63e0: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
63f0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58   to use Mac OS-X
6400: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6410: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6420: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
6430: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6440: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
6450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6460: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
6470: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
6480: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
6490: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
64a0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
64b0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
64c0: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
64d0: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
64e0: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
64f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6500: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6510: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6520: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
6530: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
6540: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
6550: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
6560: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
6570: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
6580: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
6590: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
65a0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
65b0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
65c0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
65d0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
65e0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
65f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6600: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
6610: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
6620: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
6630: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
6640: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
6650: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6660: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
6670: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
6680: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
6690: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
66a0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
66b0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
66c0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
66d0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
66e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
66f0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
6700: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
6710: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
6720: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
6730: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
6740: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
6750: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
6760: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
6770: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
6780: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
6790: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
67a0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
67b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
67c0: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
67d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
67e0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
67f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6800: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6810: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6820: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6830: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
6840: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
6850: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
6860: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
6870: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6880: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
6890: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
68a0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
68b0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
68c0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
68d0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
68e0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
68f0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
6900: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
6910: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
6920: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  s a Mac OS-X sty
6930: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
6940: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
6950: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
6960: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
6970: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
6980: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
6990: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
69a0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
69b0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
69c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
69d0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
69e0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
69f0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
6a00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
6a10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
6a20: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
6a30: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6a40: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
6a50: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6a60: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
6a70: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
6a80: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
6a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6aa0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
6ab0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
6ac0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
6ad0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
6ae0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
6af0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
6b00: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
6b10: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
6b20: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
6b30: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
6b40: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
6b50: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
6b60: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
6b70: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
6b80: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
6b90: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6ba0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6bb0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6bc0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6bd0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
6be0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
6bf0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
6c00: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
6c10: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
6c20: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
6c30: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
6c40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
6c50: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
6c60: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
6c70: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
6c80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
6c90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
6ca0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
6cb0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
6cc0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
6cd0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
6ce0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
6cf0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
6d00: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
6d10: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
6d20: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
6d30: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
6d40: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
6d50: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
6d60: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
6d70: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
6d80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
6d90: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
6da0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
6db0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
6dc0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
6dd0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
6de0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
6df0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
6e00: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
6e10: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
6e20: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
6e30: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
6e40: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
6e50: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
6e60: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
6e70: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
6e80: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
6e90: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
6ea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6eb0: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
6ec0: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
6ed0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
6ee0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
6ef0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
6f00: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
6f10: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
6f20: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
6f30: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
6f40: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6f50: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6f60: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6f70: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6f80: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6f90: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6fa0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6fb0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6fc0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
6fd0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
6fe0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
6ff0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7000: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
7010: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
7020: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
7030: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7040: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
7050: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
7060: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
7070: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
7080: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
7090: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
70a0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
70b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
70e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
70f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
7120: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7130: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7140: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7150: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7160: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7170: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
7180: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7190: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
71a0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
71b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
71c0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
71d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
71e0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
71f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
7200: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
7210: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
7220: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7230: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7240: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
7250: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
7260: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7270: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7280: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
7290: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
72a0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
72b0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
72c0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
72d0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
72e0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
72f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
7300: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
7310: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7320: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7330: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
7340: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
7350: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
7360: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
7370: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
7380: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
7390: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
73a0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
73b0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
73c0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
73d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
73e0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
73f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7400: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7410: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7420: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7430: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
7440: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
7450: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7460: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7470: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
7480: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
7490: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
74a0: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
74b0: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
74c0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
74d0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
74e0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
74f0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
7500: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
7510: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7520: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
7530: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
7540: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7550: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7560: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
7570: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
7580: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7590: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
75a0: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
75b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
75c0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
75d0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
75e0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
75f0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
7600: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7620: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
7630: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7640: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
7650: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
7660: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
7670: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
7680: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
7690: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
76a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
76b0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
76c0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
76d0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
76e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
76f0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7700: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
7710: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
7720: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7730: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
7740: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
7750: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7760: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
7770: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
7780: 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30  {H11310} <S30800
7790: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  >.**.** These in
77a0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
77b0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
77c0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
77d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
77e0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
77f0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7800: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7810: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7820: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7830: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7840: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7850: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
7860: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
7870: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
7880: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
7890: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
78a0: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
78b0: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
78c0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
78d0: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
78e0: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
78f0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7900: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7910: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7920: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7930: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
7940: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
7950: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
7960: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
7970: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
7980: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
7990: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
79a0: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
79b0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
79c0: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
79d0: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
79e0: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66  defined..*/.#def
79f0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7a00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7a10: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    1../*.** CAPI3
7a20: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
7a30: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31  e {H17110} <S201
7a40: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  30>.**.** The mu
7a50: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
7a60: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
7a70: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
7a80: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
7a90: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
7aa0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
7ab0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
7ac0: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
7ad0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
7ae0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
7af0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
7b00: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
7b10: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
7b20: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
7b30: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
7b40: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
7b50: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
7b60: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
7b70: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
7b80: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7b90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
7ba0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
7bb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7bc0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
7bd0: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30   {H11140} <S2010
7be0: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0>.**.** An inst
7bf0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
7c00: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
7c10: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
7c20: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
7c30: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
7c40: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
7c50: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
7c60: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
7c70: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
7c80: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
7c90: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
7ca0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
7cb0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
7cc0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
7cd0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
7ce0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
7cf0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
7d00: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
7d10: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
7d20: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
7d30: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
7d40: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
7d50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
7d60: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
7d70: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
7d80: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
7d90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7da0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
7db0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
7dc0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
7dd0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
7de0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
7df0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
7e00: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
7e10: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
7e20: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
7e30: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
7e40: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
7e50: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
7e60: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
7e70: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
7e80: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
7e90: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
7ea0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
7eb0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
7ec0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
7ed0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
7ee0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
7ef0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
7f00: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
7f10: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7f20: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
7f30: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
7f40: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
7f50: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
7f60: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
7f70: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
7f80: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
7f90: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
7fa0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
7fb0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
7fc0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
7fd0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
7fe0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
7ff0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
8000: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
8010: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
8020: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
8030: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
8040: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
8050: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
8060: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
8070: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
8080: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
8090: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
80a0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
80b0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
80c0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
80d0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
80e0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
80f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
8100: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
8110: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
8120: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
8130: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
8140: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
8150: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
8160: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
8170: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
8180: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
8190: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
81a0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
81b0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
81c0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
81d0: 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74  * {H11141} SQLit
81e0: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
81f0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
8200: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8210: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
8220: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
8230: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
8240: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
8250: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
8260: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
8270: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
8280: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
8290: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
82a0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
82b0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
82c0: 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63  lled. {END}  Bec
82d0: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
82e0: 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a  ious sentense,.*
82f0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
8300: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
8310: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
8320: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
8330: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
8340: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
8350: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
8360: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
8370: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8380: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20  ameter is xOpen 
8390: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
83a0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
83b0: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20  must invite its 
83c0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
83d0: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
83e0: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a    Whenever the .
83f0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
8400: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
8410: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
8420: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
8430: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
8440: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
8450: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8460: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
8470: 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65  .** {H11142} The
8480: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8490: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
84a0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
84b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
84c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
84d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
84e0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
84f0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8500: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8510: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
8520: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
8530: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
8540: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
8550: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
8560: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44  EN_CREATE]. {END
8570: 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  }.** If xOpen() 
8580: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8590: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
85a0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
85b0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
85c0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
85d0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
85e0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
85f0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
8600: 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65   {H11143} SQLite
8610: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
8620: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
8630: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
8640: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
8650: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
8660: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
8670: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
8680: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
8690: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
86a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
86b0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
86c0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
86d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
86e0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
86f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8700: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8710: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8720: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
8730: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8740: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
8750: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8760: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
8770: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NAL].** </ul> {E
8780: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ND}.**.** The fi
8790: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
87a0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
87b0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
87c0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
87d0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
87e0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
87f0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
8800: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
8810: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
8820: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
8830: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
8840: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
8850: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
8860: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
8870: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
8880: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
8890: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
88a0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
88b0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
88c0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
88d0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
88e0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
88f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
8900: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
8910: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
8920: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
8930: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
8940: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
8950: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
8960: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
8970: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
8980: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
8990: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
89a0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
89b0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
89c0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
89d0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
89e0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
89f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8a00: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8a10: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8a20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8a30: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
8a40: 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b  * {H11145} The [
8a50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8a60: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
8a70: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
8a80: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
8a90: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8aa0: 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d  losed.  {H11146}
8ab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8ac0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8ad0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8ae0: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8af0: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8b00: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8b10: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37  s..**.** {H11147
8b20: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
8b30: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
8b40: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
8b50: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
8b60: 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  ed.** for exclus
8b70: 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69  ive access.  Thi
8b80: 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f  s flag is set fo
8b90: 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65  r all files exce
8ba0: 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61  pt.** for the ma
8bb0: 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
8bc0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d  ..**.** {H11148}
8bd0: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
8be0: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
8bf0: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
8c00: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
8c10: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
8c20: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
8c30: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
8c40: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
8c50: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45  ent to xOpen. {E
8c60: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ND}  The xOpen m
8c70: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
8c80: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
8c90: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
8ca0: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
8cb0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a   fill it in..**.
8cc0: 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20  ** {H11149} The 
8cd0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8ce0: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8cf0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8d00: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
8d10: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
8d20: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
8d30: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
8d40: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
8d50: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
8d60: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
8d70: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8d80: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
8d90: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8da0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8db0: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8dc0: 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d   readable. {END}
8dd0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8de0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8df0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d  ..**.** {H11150}
8e00: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8e10: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8e20: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8e30: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8e40: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8e50: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8e60: 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65 78   {H11151} The ex
8e70: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
8e80: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8e90: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
8ea0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
8eb0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
8ec0: 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f   {END}  If the o
8ed0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8ee0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8ef0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8f00: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8f10: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8f20: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8f30: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8f40: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8f50: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8f60: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8f70: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8f80: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8f90: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8fa0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8fb0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8fc0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8fd0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8fe0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ff0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
9000: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
9010: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
9020: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
9030: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
9040: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
9050: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
9060: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
9070: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
9080: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
9090: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
90a0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
90b0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
90c0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
90d0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
90e0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
90f0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
9100: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
9110: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
9120: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
9130: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
9140: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9150: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9160: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9170: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9180: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9190: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
91a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
91b0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
91c0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
91d0: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
91e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
91f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
9200: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
9210: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
9220: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
9230: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
9240: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
9250: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e  n number */.  in
9260: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
9270: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
9280: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
9290: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
92a0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
92b0: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
92c0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
92d0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
92e0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
92f0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
9300: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
9310: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
9320: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
9330: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
9340: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
9350: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
9360: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
9370: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
9380: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
9390: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
93a0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
93b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
93c0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
93d0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
93e0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
93f0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9400: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9410: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9420: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9430: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
9440: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
9450: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
9460: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9470: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
9480: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
9490: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
94a0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
94b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
94c0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
94d0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
94e0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
94f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9500: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9510: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9520: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9530: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
9540: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
9550: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
9560: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
9570: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
9580: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
9590: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
95a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
95b0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
95c0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
95d0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
95e0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
95f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9600: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9610: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
9620: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
9630: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
9640: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
9650: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
9660: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
9670: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
9680: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
9690: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
96a0: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
96b0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
96c0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
96d0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
96e0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
96f0: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
9700: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9710: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
9720: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b  ess VFS method {
9730: 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e  H11190} <H11140>
9740: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20  .**.** {H11191} 
9750: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9760: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
9770: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
9780: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9790: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
97a0: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
97b0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
97c0: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65  {END}  They dete
97d0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
97e0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
97f0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9800: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9810: 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d  for..** {H11192}
9820: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9830: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
9840: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9850: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
9860: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9870: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31   exists..** {H11
9880: 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45  193} With SQLITE
9890: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
98a0: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
98b0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
98c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
98d0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
98e0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
98f0: 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68  ** {H11194} With
9900: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9910: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
9920: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
9930: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
9940: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
9950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9960: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
9970: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
9980: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9990: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
99a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
99b0: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
99c0: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
99d0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
99e0: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d  Library {H10130}
99f0: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30   <S20000><S30100
9a00: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
9a10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9a20: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
9a30: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
9a40: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
9a50: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9a60: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
9a70: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
9a80: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
9a90: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9aa0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9ab0: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ze()..**.** A ca
9ac0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
9ad0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
9ae0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9af0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
9b00: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
9b10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9b20: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
9b30: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
9b40: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
9b50: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
9b60: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
9b70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9b80: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
9b90: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
9ba0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9bb0: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20  utdown().  Only 
9bc0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
9bd0: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
9be0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
9bf0: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
9c00: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
9c10: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
9c20: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  rmless no-ops..*
9c30: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
9c40: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33   things, sqlite3
9c50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68  _initialize() sh
9c60: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  all invoke.** sq
9c70: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
9c80: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c    Similarly, sql
9c90: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9ca0: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20  ** shall invoke 
9cb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9cc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9cd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9ce0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75   SQLITE_OK on su
9d00: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72  ccess..** If for
9d10: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
9d20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9d30: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
9d40: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
9d50: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
9d60: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
9d70: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
9d80: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
9d90: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
9da0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
9db0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
9dc0: 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f  er than SQLITE_O
9dd0: 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  K..**.** The sql
9de0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9df0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
9e00: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
9e10: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
9e20: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9e30: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
9e40: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
9e50: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
9e60: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
9e70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9e80: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
9e90: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
9ea0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
9eb0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
9ec0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
9ed0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
9ee0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
9ef0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
9f00: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
9f10: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
9f20: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
9f30: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
9f40: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77  ** already.  How
9f50: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
9f60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9f70: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
9f80: 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d  _AUTOINIT.** com
9f90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
9fa0: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
9fb0: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
9fc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9fd0: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
9fe0: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
9ff0: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
a000: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a010: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
a020: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
a030: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
a040: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
a050: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
a060: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
a070: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
a080: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
a090: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
a0a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
a0b0: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
a0c0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
a0d0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
a0e0: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
a0f0: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
a100: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
a110: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
a120: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
a130: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
a140: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
a150: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53   compiled with S
a160: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
a170: 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  NIT might become
a180: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a190: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a1a0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a1b0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a1c0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a1d0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a1e0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a1f0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a200: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a210: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a220: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a230: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a240: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a250: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a260: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a270: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a280: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a290: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a2a0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a2b0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a2c0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a2d0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a2e0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a2f0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a300: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
a310: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
a320: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
a330: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
a340: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
a350: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
a360: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
a370: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
a380: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
a390: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a3a0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a3b0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a3c0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a3d0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a3e0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a3f0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a400: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a410: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a420: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a430: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a440: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a450: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a460: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a470: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a480: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a490: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a4a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a4b0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a4c0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a4d0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a4e0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a4f0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a500: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a510: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a520: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a530: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a540: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a550: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a560: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a570: 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  the SQLITE_OS_OT
a580: 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74 69  HER=1 compile-ti
a590: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a5a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a5b0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a5c0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a5d0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a5e0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a5f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a600: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a610: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a620: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a630: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a640: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a650: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a660: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
a670: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
a680: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
a690: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
a6a0: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
a6b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a6c0: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
a6d0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
a6e0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a6f0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
a700: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
a710: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
a720: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
a730: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
a740: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 34  e Library {H1014
a750: 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32  5} <S20000><S302
a760: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
a770: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
a780: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a790: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a7a0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a7b0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a7c0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a7d0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a7e0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a7f0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a800: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a810: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a820: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a830: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a840: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a850: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a860: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a870: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a880: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a890: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a8a0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a8b0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a8c0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a8d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a8e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a8f0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a900: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a910: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a920: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a930: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a940: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a950: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a960: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a970: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a980: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a990: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a9a0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a9b0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a9c0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a9d0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a9e0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a9f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
aa00: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
aa10: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
aa20: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65  down()]..** Note
aa30: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
aa40: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
aa50: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
aa60: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
aa70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
aa80: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
aa90: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
aaa0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
aab0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
aac0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
aad0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
aae0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
aaf0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ab00: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
ab10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
ab20: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
ab30: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
ab40: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
ab50: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
ab60: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
ab70: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
ab80: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ab90: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
aba0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
abb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
abc0: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
abd0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
abe0: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69  .** When a confi
abf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
ac00: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
ac10: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
ac20: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
ac30: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
ac40: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
ac50: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
ac60: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
ac70: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
ac80: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
ac90: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
aca0: 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  e]..*/.SQLITE_EX
acb0: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
acc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
acd0: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
ace0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
acf0: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
ad00: 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 30 31 38  nections  {H1018
ad10: 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45  0} <S20000>.** E
ad20: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
ad30: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
ad40: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ad50: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ad60: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
ad70: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
ad80: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
ad90: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
ada0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
adb0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
adc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
add0: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
ade0: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
adf0: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
ae00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
ae10: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
ae20: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
ae30: 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
ae40: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
ae50: 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79  terface can only
ae60: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
ae70: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
ae80: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
ae90: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
aea0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
aeb0: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
aec0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
aed0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
aee0: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
aef0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
af00: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
af10: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
af20: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
af30: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
af40: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
af50: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
af60: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
af70: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
af80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
af90: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
afa0: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
afb0: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
afc0: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
afd0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
afe0: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
aff0: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
b000: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
b010: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
b020: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
b030: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
b040: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
b050: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
b060: 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
b070: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
b080: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
b090: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
b0a0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
b0b0: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
b0c0: 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30  es {H10155} <S20
b0d0: 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  120>.** EXPERIME
b0e0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  NTAL.**.** An in
b0f0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
b100: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
b110: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
b120: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
b130: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
b140: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
b150: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
b160: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
b170: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
b180: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
b190: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
b1a0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
b1b0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b1c0: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
b1d0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
b1e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b1f0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
b200: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
b210: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
b220: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79  FIG_MALLOC].  By
b230: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
b240: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
b250: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
b260: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
b270: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72  e3_config()] dur
b280: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
b290: 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61  n, an.** applica
b2a0: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
b2b0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20   an alternative 
b2c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b2d0: 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66  n subsystem.** f
b2e0: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
b2f0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
b300: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
b310: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
b320: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
b330: 65 73 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d  es with a built-
b340: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
b350: 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70  tor that is.** p
b360: 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
b370: 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
b380: 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
b390: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
b3a0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
b3b0: 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
b3c0: 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
b3d0: 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
b3e0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
b3f0: 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
b400: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b410: 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
b420: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
b430: 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
b440: 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
b450: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
b460: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
b470: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
b480: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
b490: 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
b4a0: 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
b4b0: 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
b4c0: 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
b4d0: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
b4e0: 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
b4f0: 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
b500: 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
b510: 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65  he xMalloc, xFre
b520: 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20  e, and xRealloc 
b530: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
b540: 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
b550: 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20  lloc(), free(), 
b560: 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75  and realloc() fu
b570: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
b580: 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72   standard librar
b590: 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  y..**.** xSize s
b5a0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
b5b0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
b5c0: 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
b5d0: 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
b5e0: 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
b5f0: 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
b600: 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
b610: 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
b620: 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
b630: 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
b640: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
b650: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
b660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
b670: 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
b680: 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
b690: 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
b6a0: 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
b6b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
b6c0: 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
b6d0: 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
b6e0: 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
b6f0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
b700: 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
b710: 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
b720: 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
b730: 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
b740: 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
b750: 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
b760: 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
b770: 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
b780: 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  2..**.** The xIn
b790: 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
b7a0: 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
b7b0: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f   allocator.  (Fo
b7c0: 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
b7d0: 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
b7e0: 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
b7f0: 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
b800: 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
b810: 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
b820: 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
b830: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
b840: 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
b850: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
b860: 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
b870: 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
b880: 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
b890: 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
b8a0: 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
b8b0: 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
b8c0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
b8d0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
b8e0: 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
b8f0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
b900: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
b910: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
b920: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
b930: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
b940: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
b950: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
b960: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
b970: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
b980: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
b990: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
b9a0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
b9b0: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
b9c0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
b9d0: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
b9e0: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
b9f0: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
ba00: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
ba10: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
ba20: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
ba30: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
ba40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
ba50: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
ba60: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
ba70: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
ba80: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
ba90: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
baa0: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
bab0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
bac0: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
bad0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bae0: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
baf0: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
bb00: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
bb10: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
bb20: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
bb30: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
bb40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
bb50: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
bb60: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
bb70: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
bb80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
bb90: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
bba0: 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30  ns {H10160} <S20
bbb0: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  000>.** EXPERIME
bbc0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  NTAL.**.** These
bbd0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
bbe0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
bbf0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
bc00: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
bc10: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
bc20: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
bc30: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
bc40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
bc50: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
bc60: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
bc70: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
bc80: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
bc90: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
bca0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
bcb0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
bcc0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
bcd0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
bce0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
bcf0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
bd00: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
bd10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
bd20: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
bd30: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
bd40: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
bd50: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
bd60: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
bd70: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
bd80: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
bd90: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
bda0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
bdb0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
bdc0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
bdd0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
bde0: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
bdf0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
be00: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
be10: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
be20: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
be30: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
be40: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a  option disables.
be50: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
be60: 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
be70: 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
be80: 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
be90: 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
bea0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64  ngle thread.</dd
beb0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
bec0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
bed0: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
bee0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
bef0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
bf00: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
bf10: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
bf20: 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
bf30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bf40: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
bf50: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
bf60: 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
bf70: 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
bf80: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
bf90: 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
bfa0: 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
bfb0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
bfc0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
bfd0: 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
bfe0: 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
bff0: 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
c000: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
c010: 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
c020: 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
c030: 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c  ** environment.<
c040: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c050: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
c060: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
c070: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
c080: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
c090: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
c0a0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
c0b0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
c0c0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
c0d0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
c0e0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
c0f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
c100: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
c110: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
c120: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
c130: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
c140: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
c150: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
c160: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
c170: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
c180: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
c190: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
c1a0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
c1b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c1c0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
c1d0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
c1e0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
c1f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
c200: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
c210: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
c220: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
c230: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
c240: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
c250: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
c260: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
c270: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54 68  ime..**.** <p>Th
c280: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
c290: 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79 20 73   option merely s
c2a0: 65 74 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  ets the default 
c2b0: 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68 61 76 69  mutex .** behavi
c2c0: 6f 72 20 74 6f 20 73 65 72 69 61 6c 69 7a 65 20  or to serialize 
c2d0: 61 63 63 65 73 73 20 74 6f 20 5b 64 61 74 61 62  access to [datab
c2e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
c2f0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  .  Individual.**
c300: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c310: 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76 65 72  ctions] can over
c320: 72 69 64 65 20 74 68 69 73 20 73 65 74 74 69 6e  ride this settin
c330: 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  g.** using the [
c340: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
c350: 54 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b 73 71  TEX] flag to [sq
c360: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c370: 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  .</p></dd>.**.**
c380: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c390: 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
c3a0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c3b0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c3c0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c3d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c3e0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
c3f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
c400: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
c410: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
c420: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
c430: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
c440: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
c450: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
c460: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
c470: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
c480: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c490: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
c4a0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f  t into SQLite.</
c4b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c4c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c4d0: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
c4e0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
c4f0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
c500: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
c510: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
c520: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
c530: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
c540: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c550: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
c560: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
c570: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
c580: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
c590: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
c5a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c5b0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54  n routines..** T
c5c0: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
c5d0: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
c5e0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
c5f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c600: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
c610: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
c620: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
c630: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
c640: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
c650: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
c660: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f  , for example.</
c670: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c680: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c690: 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
c6a0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
c6b0: 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
c6c0: 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
c6d0: 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
c6e0: 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
c6f0: 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
c700: 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
c710: 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
c720: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
c730: 20 73 74 61 74 69 73 74 69 63 73 2e 20 57 68 65   statistics. Whe
c740: 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  n disabled, the 
c750: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
c760: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
c770: 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61  me .** non-opera
c780: 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
c790: 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
c7a0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
c7b0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
c7c0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
c7d0: 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
c7e0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
c7f0: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
c800: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c810: 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
c820: 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64     </ul>.** </dd
c830: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c840: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
c850: 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
c860: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
c870: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
c880: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
c890: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
c8a0: 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
c8b0: 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
c8c0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
c8d0: 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  :  A pointer to 
c8e0: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a  the memory, the.
c8f0: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
c900: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28  scratch buffer (
c910: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
c920: 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28  ber of buffers (
c930: 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
c940: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
c950: 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
c960: 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74  . The sz paramet
c970: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66  er should be a f
c980: 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67  ew bytes.** larg
c990: 65 72 20 74 68 61 6e 20 74 68 65 20 61 63 74 75  er than the actu
c9a0: 61 6c 20 73 63 72 61 74 63 68 20 73 70 61 63 65  al scratch space
c9b0: 20 72 65 71 75 69 72 65 64 20 64 75 65 20 69 6e   required due in
c9c0: 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e  ternal overhead.
c9d0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  .** The first.**
c9e0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
c9f0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
ca00: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
ca10: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
ca20: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
ca30: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
ca40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
ca50: 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20  ratch buffer at 
ca60: 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c  once per thread,
ca70: 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   so.** N should 
ca80: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78  be set to the ex
ca90: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
caa0: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
cab0: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72  .  The sz.** par
cac0: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
cad0: 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a   6 times the siz
cae0: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
caf0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
cb00: 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20  ize..** Scratch 
cb10: 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64  buffers are used
cb20: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
cb30: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70  btree balance op
cb40: 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20  eration.  If.** 
cb50: 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  The btree balanc
cb60: 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  er needs additio
cb70: 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  nal memory beyon
cb80: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
cb90: 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68  ed by.** scratch
cba0: 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e   buffers or if n
cbb0: 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
cbc0: 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66   space is specif
cbd0: 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ied, then SQLite
cbe0: 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  .** goes to [sql
cbf0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74  ite3_malloc()] t
cc00: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
cc10: 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64  ory it needs.</d
cc20: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cc30: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
cc40: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
cc50: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
cc60: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
cc70: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
cc80: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
cc90: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
cca0: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
ccb0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
ccc0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20  ee arguments: A 
ccd0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
cce0: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
ccf0: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
cd00: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
cd10: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
cd20: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
cd30: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73   sz argument mus
cd40: 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20  t be a power of 
cd50: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
cd60: 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20  and 32768.  The 
cd70: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
cd80: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
cd90: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
cda0: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
cdb0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
cdc0: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ..** SQLite will
cdd0: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
cde0: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
cdf0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
ce00: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
ce10: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
ce20: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
ce30: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
ce40: 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61   to cache.  If a
ce50: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
ce60: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
ce70: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
ce80: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ce90: 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
cea0: 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
ceb0: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
cec0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
ced0: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
cee0: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
cef0: 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
cf00: 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65  on might use one
cf10: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
cf20: 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c  N buffers to hol
cf30: 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63  d .** memory acc
cf40: 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74  ounting informat
cf50: 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ion. </dd>.**.**
cf60: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
cf70: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
cf80: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
cf90: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
cfa0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
cfb0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cfc0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
cfd0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
cfe0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cff0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
d000: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
d010: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
d020: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
d030: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
d040: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
d050: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
d060: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
d070: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
d080: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72  mory, the number
d090: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
d0a0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
d0b0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
d0c0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
d0d0: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66  ze.  If.** the f
d0e0: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
d0f0: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
d100: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
d110: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
d120: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
d130: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
d140: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
d150: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
d160: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
d170: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
d180: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
d190: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
d1a0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65  MALLOC].  If the
d1b0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
d1c0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
d1d0: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
d1e0: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
d1f0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
d200: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
d210: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
d220: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
d230: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
d240: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
d250: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
d260: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
d270: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
d280: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
d290: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d2a0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
d2b0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d2c0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d2d0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d2e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d2f0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d300: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d310: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d320: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
d330: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
d340: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
d350: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
d360: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
d370: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
d380: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
d390: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
d3a0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
d3b0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
d3c0: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
d3d0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
d3e0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d3f0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d400: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
d410: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
d420: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
d430: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
d440: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
d450: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
d460: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
d470: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
d480: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
d490: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
d4a0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
d4b0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
d4c0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
d4d0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
d4e0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
d4f0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
d500: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
d510: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
d520: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
d530: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
d540: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
d550: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  xample.</dd>.**.
d560: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d570: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
d580: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
d590: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
d5a0: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
d5b0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
d5c0: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
d5d0: 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73  allcation lookas
d5e0: 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ide optimization
d5f0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
d600: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
d610: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
d620: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
d630: 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
d640: 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
d650: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
d660: 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
d670: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d680: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  n.</dd>.**.** </
d690: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
d6a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
d6b0: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
d6c0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
d6d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d6e0: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
d6f0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
d700: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
d710: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
d720: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
d730: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d740: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
d750: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
d760: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
d770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d780: 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
d790: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
d7a0: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
d7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d7c0: 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
d7d0: 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
d7e0: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
d7f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d800: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
d810: 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
d820: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
d830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d840: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
d850: 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
d860: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
d870: 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
d880: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d890: 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
d8a0: 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
d8b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d8c0: 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
d8d0: 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
d8e0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
d8f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d900: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
d910: 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
d920: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
d930: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
d940: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
d950: 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f 2a 20  KALLOC   12  /* 
d960: 69 6e 74 20 74 68 72 65 73 68 6f 6c 64 20 2a 2f  int threshold */
d970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d980: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
d990: 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
d9a0: 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  nt */../*.** CAP
d9b0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d9c0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d9d0: 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0170} <S20000>.*
d9e0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d9f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
da00: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
da10: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
da20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
da30: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
da40: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
da50: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
da60: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
da70: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
da80: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
da90: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
daa0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
dab0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
dac0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
dad0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
dae0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
daf0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
db00: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
db10: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
db20: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
db30: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
db40: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
db50: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
db60: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
db70: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
db80: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
db90: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
dba0: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
dbb0: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
dbc0: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
dbd0: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
dbe0: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
dbf0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
dc00: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
dc10: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
dc20: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
dc30: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
dc40: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
dc50: 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
dc60: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
dc70: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
dc80: 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
dc90: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
dca0: 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
dcb0: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
dcc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
dcd0: 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
dce0: 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
dcf0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
dd00: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
dd10: 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
dd20: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
dd30: 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
dd40: 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
dd50: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 72  memory.  The fir
dd60: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  st.** argument m
dd70: 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
dd80: 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
dd90: 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
dda0: 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62  e lookaside.** b
ddb0: 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
ddc0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
ddd0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f  oc()].  The seco
dde0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
ddf0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
de00: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
de10: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
de20: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
de30: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
de40: 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
de50: 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
de60: 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
de70: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
de80: 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
de90: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
dea0: 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
deb0: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
dec0: 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e   arguments.</dd>
ded0: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
dee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
def0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
df00: 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
df10: 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
df20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
df30: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
df40: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
df50: 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30  lt Codes {H12200
df60: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
df70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
df80: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
df90: 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
dfa0: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
dfb0: 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
dfc0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
dfd0: 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
dfe0: 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  e. The extended 
dff0: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
e000: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
e010: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
e020: 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
e030: 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69  lity considerati
e040: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ons..**.** INVAR
e050: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
e060: 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b  2201} Each new [
e070: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e080: 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20  ion] shall have 
e090: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
e0a0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
e0b0: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
e0c0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
e0d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ult..**.** {H122
e0e0: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
e0f0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
e100: 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74  _codes(D,F)] int
e110: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61  erface shall ena
e120: 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
e130: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
e140: 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20   codes] for the 
e150: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e160: 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
e170: 20 20 20 20 20 69 66 20 74 68 65 20 46 20 70 61       if the F pa
e180: 72 61 6d 65 74 65 72 20 69 73 20 74 72 75 65 2c  rameter is true,
e190: 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 6d   or disable them
e1a0: 20 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e 0a   if F is false..
e1b0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
e1c0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
e1d0: 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
e1e0: 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
e1f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
e200: 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48   Insert Rowid {H
e210: 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a  12220} <S10700>.
e220: 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79  **.** Each entry
e230: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
e240: 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
e250: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
e260: 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
e270: 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22  lled the "rowid"
e280: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61  . The rowid is a
e290: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
e2a0: 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
e2b0: 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
e2c0: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
e2d0: 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
e2e0: 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
e2f0: 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
e300: 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
e310: 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
e320: 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61  ns. If.** the ta
e330: 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
e340: 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45 52   of type INTEGER
e350: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65   PRIMARY KEY the
e360: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
e370: 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
e380: 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
e390: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
e3a0: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
e3b0: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73  rowid of the mos
e3c0: 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
e3d0: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e  essful INSERT in
e3e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
e3f0: 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
e400: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
e410: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
e420: 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20  rgument.  If no 
e430: 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52  successful INSER
e440: 54 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  Ts.** have ever 
e450: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
e460: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e470: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
e480: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
e490: 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72   an INSERT occur
e4a0: 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
e4b0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77  er, then the row
e4c0: 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  id of the insert
e4d0: 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
e4e0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
e4f0: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
e500: 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
e510: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
e520: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
e530: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
e540: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
e550: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
e560: 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
e570: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
e580: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
e590: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
e5a0: 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20  **.** An INSERT 
e5b0: 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
e5c0: 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
e5d0: 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
e5e0: 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
e5f0: 49 4e 53 45 52 54 20 61 6e 64 20 64 6f 65 73 20  INSERT and does 
e600: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
e610: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
e620: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
e630: 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f  .  Thus INSERT O
e640: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
e650: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
e660: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
e670: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
e680: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
e690: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
e6a0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
e6b0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
e6c0: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
e6d0: 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e   fails.  When IN
e6e0: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
e6f0: 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
e700: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
e710: 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
e720: 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
e730: 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
e740: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
e750: 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
e760: 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
e770: 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
e780: 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
e790: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
e7a0: 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
e7b0: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
e7c0: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
e7d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  erface..**.** Fo
e7e0: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
e7f0: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
e800: 61 6e 20 49 4e 53 45 52 54 20 69 73 20 63 6f 6e  an INSERT is con
e810: 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
e820: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
e830: 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
e840: 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
e850: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ck..**.** INVARI
e860: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
e870: 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  221} The [sqlite
e880: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
e890: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
e8a0: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
e8b0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  d.**          of
e8c0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
e8d0: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
e8e0: 52 54 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20  RT performed on 
e8f0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
e900: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
e910: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77  onnection] and w
e920: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  ithin the same o
e930: 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a  r higher level.*
e940: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
e950: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a  er context, or z
e960: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76  ero if there hav
e970: 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66  e been no qualif
e980: 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a  ying inserts..**
e990: 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65  .** {H12223} The
e9a0: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
e9b0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
e9c0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
e9d0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
e9e0: 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20  same value when 
e9f0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
ea00: 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e  same trigger con
ea10: 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
ea20: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
ea30: 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20  ore and after a 
ea40: 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20  ROLLBACK..**.** 
ea50: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
ea60: 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61  ** {A12232} If a
ea70: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
ea80: 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
ea90: 49 4e 53 45 52 54 20 6f 6e 20 74 68 65 20 73 61  INSERT on the sa
eaa0: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  me.**          d
eab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
eac0: 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
ead0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
eae0: 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20  t_rowid()].**   
eaf0: 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
eb00: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
eb10: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
eb20: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
eb30: 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  d,.**          t
eb40: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
eb50: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
eb60: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
eb70: 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20  owid()] is.**   
eb80: 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74         unpredict
eb90: 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
eba0: 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
ebb0: 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
ebc0: 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ew.**          l
ebd0: 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
ebe0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
ebf0: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
ec00: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
ec10: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
ec20: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
ec30: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
ec40: 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32  s Modified {H122
ec50: 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a  40} <S10600>.**.
ec60: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
ec70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
ec80: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
ec90: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
eca0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
ecb0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
ecc0: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
ecd0: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
ece0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
ecf0: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
ed00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
ed10: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
ed20: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
ed30: 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ** Only changes 
ed40: 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
ed50: 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
ed60: 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
ed70: 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54 45 20  E,.** or DELETE 
ed80: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
ed90: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
eda0: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
edb0: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
edc0: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
edd0: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
ede0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
edf0: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
ee00: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
ee10: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
ee20: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
ee30: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
ee40: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
ee50: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
ee60: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
ee70: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
ee80: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
ee90: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
eea0: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
eeb0: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
eec0: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
eed0: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
eee0: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
eef0: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
ef00: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
ef10: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
ef20: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
ef30: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
ef40: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
ef50: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
ef60: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
ef70: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
ef80: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
ef90: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
efa0: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
efb0: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
efc0: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
efd0: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
efe0: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
eff0: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
f000: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
f010: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
f020: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
f030: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
f040: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
f050: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
f060: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
f070: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
f080: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
f090: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
f0a0: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
f0b0: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
f0c0: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
f0d0: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
f0e0: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
f0f0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
f100: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
f110: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
f120: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
f130: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
f140: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
f150: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
f160: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
f170: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
f180: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
f190: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
f1a0: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
f1b0: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
f1c0: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
f1d0: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
f1e0: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
f1f0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
f200: 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
f210: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
f220: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
f230: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
f240: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
f250: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
f260: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
f270: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
f280: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
f290: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
f2a0: 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69  op level.  Withi
f2b0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
f2c0: 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
f2d0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f2e0: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
f2f0: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
f300: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
f310: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
f320: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
f330: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
f340: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
f350: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
f360: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
f370: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
f380: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
f390: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
f3a0: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
f3b0: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
f3c0: 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
f3d0: 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
f3e0: 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
f3f0: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
f400: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
f410: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
f420: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
f430: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
f440: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
f450: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
f460: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
f470: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
f480: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
f490: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
f4a0: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
f4b0: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
f4c0: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
f4d0: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
f4e0: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
f4f0: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
f500: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
f510: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
f520: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
f530: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
f540: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
f550: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
f560: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
f570: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
f580: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
f590: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
f5a0: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
f5b0: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
f5c0: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
f5d0: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
f5e0: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
f5f0: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
f600: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
f610: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
f620: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
f630: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
f640: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
f650: 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 68 65  .** {H12241} The
f660: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
f670: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  s()] function sh
f680: 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  all return the n
f690: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
f6a0: 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73       row changes
f6b0: 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d   caused by the m
f6c0: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
f6d0: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20  T, UPDATE,.**   
f6e0: 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45         or DELETE
f6f0: 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
f700: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
f710: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a  connection and.*
f720: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69  *          withi
f730: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
f740: 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e  gher trigger con
f750: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
f760: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
f770: 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
f780: 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
f790: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
f7a0: 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 61 74  ** {H12243} Stat
f7b0: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
f7c0: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
f7d0: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
f7e0: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
f7f0: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
f800: 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65  l cause subseque
f810: 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  nt calls to.**  
f820: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
f830: 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72  _changes()] to r
f840: 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61  eturn zero, rega
f850: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a  rdless of the.**
f860: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
f870: 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61   of rows origina
f880: 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
f890: 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
f8a0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
f8b0: 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
f8c0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
f8d0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
f8e0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
f8f0: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
f900: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
f910: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
f920: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
f930: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
f940: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
f950: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
f960: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
f970: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f980: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
f990: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f9a0: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
f9b0: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
f9c0: 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36  d {H12260} <S106
f9d0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
f9e0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
f9f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
fa00: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
fa10: 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55   by INSERT,.** U
fa20: 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
fa30: 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
fa40: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
fa50: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
fa60: 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f  pened..** The co
fa70: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
fa80: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
fa90: 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  l trigger contex
faa0: 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ts.  However,.**
fab0: 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
fac0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
fad0: 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
fae0: 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f  ement REPLACE co
faf0: 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
fb00: 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
fb10: 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
fb20: 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72  or DROP table pr
fb30: 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65  ocessing..** The
fb40: 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
fb50: 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  nted as soon as 
fb60: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
fb70: 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
fb80: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77  .** completed (w
fb90: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
fba0: 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73  t handle is pass
fbb0: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
fbc0: 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
fbd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
fbe0: 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  )])..**.** SQLit
fbf0: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
fc00: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
fc10: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
fc20: 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61  hout a WHERE cla
fc30: 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69  use.** by droppi
fc40: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
fc50: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
fc60: 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74  his is much fast
fc70: 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
fc80: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
fc90: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
fca0: 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
fcb0: 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
fcc0: 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f  use of this.** o
fcd0: 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
fce0: 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44   deletions in "D
fcf0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
fd00: 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68  " are not row ch
fd10: 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c  anges and.** wil
fd20: 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  l not be counted
fd30: 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
fd40: 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71  changes() or [sq
fd50: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
fd60: 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  ges()].** functi
fd70: 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20  ons, regardless 
fd80: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
fd90: 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
fda0: 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  ere originally.*
fdb0: 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20  * in the table. 
fdc0: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
fdd0: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
fde0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
fdf0: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
fe00: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
fe10: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
fe20: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ead..**.** See a
fe30: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
fe40: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
fe50: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  rface..**.** INV
fe60: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
fe70: 48 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c  H12261} The [sql
fe80: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
fe90: 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68  es()] returns th
fea0: 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a  e total number.*
feb0: 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f  *          of ro
fec0: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
fed0: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
fee0: 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54  TE, and/or DELET
fef0: 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  E.**          st
ff00: 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20  atements on the 
ff10: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
ff20: 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61  onnection], in a
ff30: 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ny.**          t
ff40: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
ff50: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
ff60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
ff70: 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  s created..**.**
ff80: 20 7b 48 31 32 32 36 33 7d 20 53 74 61 74 65 6d   {H12263} Statem
ff90: 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ents of the form
ffa0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
ffb0: 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f  blename" with no
ffc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45  .**          WHE
ffd0: 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20  RE clause shall 
ffe0: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
fff0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
10000 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [sq
10010 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
10020 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  ges()]..**.** AS
10030 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
10040 20 7b 41 31 32 32 36 34 7d 20 49 66 20 61 20 73   {A12264} If a s
10050 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
10060 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
10070 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
10080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
10090 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b           while [
100a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
100b0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
100c0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
100d0 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ue.**          r
100e0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
100f0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
10100 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
10110 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
10120 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
10130 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10140 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
10150 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
10160 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c 53  uery {H12270} <S
10170 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30500>.**.** Thi
10180 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
10190 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
101a0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
101b0 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
101c0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
101d0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
101e0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
101f0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
10200 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
10210 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
10220 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
10230 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
10240 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
10250 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
10260 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
10270 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
10280 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
10290 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66  .**.** It is saf
102a0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
102b0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
102c0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
102d0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
102e0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
102f0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
10300 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
10310 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
10320 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
10330 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
10340 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
10350 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
10360 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
10370 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
10380 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
10390 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
103a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
103b0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
103c0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
103d0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
103e0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
103f0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
10400 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
10410 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
10420 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
10430 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
10440 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
10450 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
10460 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c  on..**.** An SQL
10470 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
10480 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
10490 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
104a0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
104b0 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75  * If the interru
104c0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
104d0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
104e0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
104f0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
10500 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
10510 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
10520 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
10530 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
10540 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
10550 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
10560 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
10570 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10580 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63  t() has no effec
10590 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
105a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
105b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 73 71  started after sq
105c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
105d0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
105e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
105f0 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54 68 65 20  ** {H12271} The 
10600 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
10610 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  pt()] interface 
10620 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72  will force all r
10630 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  unning.**       
10640 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
10650 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
10660 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  h the same datab
10670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
10680 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 68 61  *          to ha
10690 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65 73 73  lt after process
106a0 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20  ing at most one 
106b0 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f  additional row o
106c0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48  f data..**.** {H
106d0 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73  12272} Any SQL s
106e0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73  tatement that is
106f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20   interrupted by 
10700 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
10710 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  pt()].**        
10720 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53    will return [S
10730 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
10740 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
10750 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
10760 37 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62  79} If the datab
10770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
10780 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
10790 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
107a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
107b0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
107c0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
107d0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
107e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
107f0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
10800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10810 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
10820 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
10830 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31   Is Complete {H1
10840 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a  0510} <S70200>.*
10850 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
10860 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66  nes are useful f
10870 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  or command-line 
10880 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
10890 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
108a0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
108b0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
108c0 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c  m complete a SQL
108d0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
108e0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
108f0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
10900 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
10910 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
10920 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
10930 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  g.  These routin
10940 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  es return true i
10950 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
10960 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
10970 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
10980 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41  QL statement.  A
10990 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
109a0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
109b0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
109c0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
109d0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
109e0 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f  not a fragment o
109f0 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52  f a.** CREATE TR
10a00 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
10a10 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61    Semicolons tha
10a20 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
10a30 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
10a40 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
10a50 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
10a60 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
10a70 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
10a80 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
10a90 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
10aa0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
10ab0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
10ac0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
10ad0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
10ae0 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
10af0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
10b00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
10b10 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
10b20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
10b30 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
10b40 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
10b50 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
10b60 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  QL..**.** INVARI
10b70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
10b80 35 31 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  511} A successfu
10b90 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  l evaluation of 
10ba0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10bb0 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
10bc0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d      [sqlite3_com
10bd0 70 6c 65 74 65 31 36 28 29 5d 20 66 75 6e 63 74  plete16()] funct
10be0 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ions shall.**   
10bf0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 20         return a 
10c00 6e 75 6d 65 72 69 63 20 31 20 69 66 20 61 6e 64  numeric 1 if and
10c10 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73   only if the las
10c20 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65  t non-whitespace
10c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b  .**          tok
10c40 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75  en in their inpu
10c50 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  t is a semicolon
10c60 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69 6e 20   that is not in 
10c70 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20  between.**      
10c80 20 20 20 20 74 68 65 20 42 45 47 49 4e 20 61 6e      the BEGIN an
10c90 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54  d END of a CREAT
10ca0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
10cb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  ent..**.** {H105
10cc0 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  12} If a memory 
10cd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
10ce0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61   occurs during a
10cf0 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20  n invocation.** 
10d00 20 20 20 20 20 20 20 20 20 6f 66 20 5b 73 71 6c           of [sql
10d10 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
10d20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   or [sqlite3_com
10d30 70 6c 65 74 65 31 36 28 29 5d 20 74 68 65 6e 20  plete16()] then 
10d40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
10d50 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
10d60 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  turn [SQLITE_NOM
10d70 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  EM]..**.** ASSUM
10d80 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
10d90 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74  10512} The input
10da0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
10db0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
10dc0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
10dd0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
10de0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
10df0 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54 68 65 20  ** {A10513} The 
10e00 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
10e10 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
10e20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
10e30 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
10e40 20 20 20 20 20 20 55 54 46 2d 31 36 20 73 74 72        UTF-16 str
10e50 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
10e60 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
10e70 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
10e80 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
10e90 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
10ea0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
10eb0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
10ec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
10ed0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
10ee0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
10ef0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b  TE_BUSY Errors {
10f00 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e  H12310} <S40400>
10f10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
10f20 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
10f30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
10f40 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
10f50 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
10f60 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
10f70 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
10f80 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
10f90 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
10fa0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
10fb0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49   locked..**.** I
10fc0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
10fd0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
10fe0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
10ff0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11000 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
11010 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
11020 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
11030 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
11040 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
11050 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
11060 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
11070 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20  allback will be 
11080 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
11090 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
110a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
110b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
110c0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
110d0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
110e0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
110f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
11100 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
11110 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68  y_handler().  Th
11120 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11130 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
11140 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
11150 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
11160 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
11170 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
11180 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
11190 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
111a0 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a  vent.  If the.**
111b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
111c0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
111d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
111e0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
111f0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
11200 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
11210 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
11220 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
11230 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
11240 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
11250 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
11260 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
11270 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
11280 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
11290 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
112a0 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
112b0 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
112c0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
112d0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
112e0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
112f0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
11300 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
11310 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
11320 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
11330 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
11340 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
11350 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
11360 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
11370 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
11380 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
11390 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
113a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
113b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
113c0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
113d0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
113e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
113f0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
11400 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
11410 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
11420 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
11430 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
11440 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
11450 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
11460 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
11470 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
11480 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
11490 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
114a0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
114b0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
114c0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
114d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
114e0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
114f0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
11500 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
11510 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
11520 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
11530 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
11540 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
11550 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
11560 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
11570 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
11580 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11590 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
115a0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
115b0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
115c0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
115d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
115e0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
115f0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
11600 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
11610 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
11620 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
11630 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
11640 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
11650 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
11660 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
11670 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
11680 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
11690 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
116a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
116b0 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
116c0 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
116d0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
116e0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
116f0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
11700 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
11710 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
11720 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
11730 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
11740 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
11750 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
11760 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
11770 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
11780 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
11790 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
117a0 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
117b0 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
117c0 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
117d0 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
117e0 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
117f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
11800 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
11810 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
11820 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20  readers.  If it 
11830 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
11840 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
11850 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
11860 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
11870 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
11880 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
11890 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
118a0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
118b0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
118c0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
118d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
118e0 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
118f0 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
11900 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68  RR_BLOCKED].  Th
11910 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
11920 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
11930 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
11940 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
11950 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
11960 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
11970 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
11980 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
11990 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
119a0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
119b0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
119c0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
119d0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
119e0 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
119f0 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ortant..**.** Th
11a00 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
11a10 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
11a20 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
11a30 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
11a40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
11a50 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
11a60 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
11a70 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
11a80 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
11a90 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61  r.  Note that ca
11aa0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
11ab0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
11ac0 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
11ad0 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
11ae0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
11af0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
11b00 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68 65 20  ** {H12311} The 
11b10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
11b20 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20 66 75  ndler(D,C,A)] fu
11b30 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 70  nction shall rep
11b40 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lace.**         
11b50 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
11b60 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
11b70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 69  connection] D wi
11b80 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  th a new.**     
11b90 20 20 20 20 20 61 20 6e 65 77 20 62 75 73 79 20       a new busy 
11ba0 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61 70  handler C and ap
11bb0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
11bc0 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20  ointer A..**.** 
11bd0 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79 20 63  {H12312} Newly c
11be0 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73 65  reated [database
11bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68   connections] sh
11c00 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73 79 0a  all have a busy.
11c10 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
11c20 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ler of NULL..**.
11c30 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68 65 6e  ** {H12314} When
11c40 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b 64 61   two or more [da
11c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c60 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a 20 20  ns] share a.**  
11c70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
11c80 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
11c90 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61  ache | common ca
11ca0 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  che],.**        
11cb0 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c    the busy handl
11cc0 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
11cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
11ce0 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a  urrently using.*
11cf0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
11d00 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20 69 6e  ache shall be in
11d10 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63  voked when the c
11d20 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  ache encounters 
11d30 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  a lock..**.** {H
11d40 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79  12316} If a busy
11d50 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
11d60 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  k returns zero, 
11d70 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 20  then the SQLite 
11d80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20  interface.**    
11d90 20 20 20 20 20 20 74 68 61 74 20 70 72 6f 76 6f        that provo
11da0 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20  ked the locking 
11db0 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74 75  event shall retu
11dc0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
11dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 38 7d  ..**.** {H12318}
11de0 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20 69 6e   SQLite shall in
11df0 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68  vokes the busy h
11e00 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20  andler with two 
11e10 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68 0a  arguments which.
11e20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
11e30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f  a copy of the po
11e40 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20 62  inter supplied b
11e50 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  y the 3rd parame
11e60 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
11e70 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
11e80 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20  _handler()] and 
11e90 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  a count of the n
11ea0 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a  umber of prior.*
11eb0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63  *          invoc
11ec0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  ations of the bu
11ed0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74  sy handler for t
11ee0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
11ef0 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  event..**.** ASS
11f00 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
11f10 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73 79 20  {A12319} A busy 
11f20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
11f30 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
11f40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
11f50 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70  *          or [p
11f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11f70 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
11f80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11f90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11fa0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
11fb0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
11fc0 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
11fd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11fe0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
11ff0 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20  imeout {H12340} 
12000 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40410>.**.** T
12010 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
12020 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
12030 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
12040 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
12050 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
12060 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
12070 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
12080 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
12090 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
120a0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
120b0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
120c0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
120d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
120e0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
120f0 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33  cumulated. {H123
12100 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d  43} After "ms" m
12110 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
12120 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
12130 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
12140 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
12150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
12160 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
12170 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
12180 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12190 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  KED]..**.** Call
121a0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
121b0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
121c0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
121d0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
121e0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
121f0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
12200 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
12210 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
12220 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
12230 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
12240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12250 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
12260 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
12270 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
12280 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
12290 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
122a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
122b0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
122c0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
122d0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
122e0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
122f0 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a  s cleared..**.**
12300 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
12310 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68 65 20  ** {H12341} The 
12320 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
12330 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f  meout()] functio
12340 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65  n shall override
12350 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20   any prior.**   
12360 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
12370 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
12380 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  or [sqlite3_busy
12390 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74  _handler()] sett
123a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
123b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
123c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
123d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 33  ]..**.** {H12343
123e0 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  } If the 2nd par
123f0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
12400 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
12410 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a  )] is less than.
12420 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65  **          or e
12430 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68  qual to zero, th
12440 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  en the busy hand
12450 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63 6c 65  ler shall be cle
12460 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20  ared so that.** 
12470 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62           all sub
12480 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20  sequent locking 
12490 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65  events immediate
124a0 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ly return [SQLIT
124b0 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_BUSY]..**.** {
124c0 48 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32  H12344} If the 2
124d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
124e0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
124f0 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f  meout()] is a po
12500 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
12510 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65     number N, the
12520 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  n a busy handler
12530 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20 74 68   shall be set th
12540 61 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61  at repeatedly ca
12550 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
12560 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
12570 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71 6c 69  hod in the [sqli
12580 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20 69 6e  te3_vfs | VFS in
12590 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c 0a 2a  terface] until.*
125a0 2a 20 20 20 20 20 20 20 20 20 20 65 69 74 68 65  *          eithe
125b0 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65 61 72  r the lock clear
125c0 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63  s or until the c
125d0 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20  umulative sleep 
125e0 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  time.**         
125f0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 62   reported back b
12600 79 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65  y xSleep() excee
12610 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  ds N millisecond
12620 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
12630 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
12640 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
12650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12660 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
12670 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
12680 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32  ing Queries {H12
12690 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  370} <S10000>.**
126a0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
126b0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
126c0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
126d0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
126e0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
126f0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
12700 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
12710 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
12720 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
12730 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
12740 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
12750 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
12760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
12770 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
12780 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
12790 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
127a0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
127b0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
127c0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
127d0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
127e0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
127f0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
12800 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
12810 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
12820 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
12830 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
12840 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
12850 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
12860 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
12870 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
12880 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
12890 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
128a0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
128b0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
128c0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
128d0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
128e0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
128f0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
12900 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
12910 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
12920 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
12930 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
12940 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
12950 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
12960 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
12970 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
12980 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
12990 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
129a0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
129b0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
129c0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
129d0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
129e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
129f0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
12a00 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
12a10 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
12a20 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
12a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
12a40 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
12a50 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
12a60 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
12a70 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
12a80 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
12a90 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
12aa0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
12ab0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
12ac0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
12ad0 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70  *.** As an examp
12ae0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
12af0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
12b00 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
12b10 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
12b20 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
12b30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b40 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
12b50 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
12b60 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
12b70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
12b80 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
12b90 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
12ba0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
12bb0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
12bc0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
12bd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
12be0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
12bf0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
12c00 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
12c10 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
12c20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
12c30 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
12c40 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
12c50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12c60 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
12c70 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
12c80 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
12c90 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
12ca0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
12cb0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12cc0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
12cd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
12ce0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
12cf0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12d00 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
12d10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
12d20 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
12d30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12d40 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
12d50 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
12d60 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
12d70 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
12d80 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
12d90 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
12da0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12db0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
12dc0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12dd0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
12de0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12df0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
12e00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12e10 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
12e20 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
12e30 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
12e40 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
12e50 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
12e60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12e70 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
12e80 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
12e90 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72  meter.  It retur
12ea0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
12eb0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
12ec0 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
12ed0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
12ee0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
12ef0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
12f00 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
12f10 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20  ing the result, 
12f20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73  it should.** pas
12f30 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  s the pointer to
12f40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12f50 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  e to sqlite3_fre
12f60 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
12f70 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
12f80 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
12f90 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
12fa0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
12fb0 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
12fc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
12fd0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
12fe0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
12ff0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
13000 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
13010 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
13020 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
13030 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
13040 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
13050 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
13060 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
13070 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
13080 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
13090 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
130a0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
130b0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
130c0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
130d0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
130e0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
130f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
13100 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
13110 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
13120 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
13130 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
13140 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
13150 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
13160 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
13170 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
13180 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
13190 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
131a0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
131b0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
131c0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
131d0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
131e0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
131f0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
13200 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
13210 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
13220 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
13230 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
13240 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  g()]..**.** INVA
13250 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
13260 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c  12371} If a [sql
13270 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13280 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79  ] fails a memory
13290 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
132a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
132b0 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68 65 20   shall free the 
132c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64  result table und
132d0 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c  er construction,
132e0 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 20 20   abort the.**   
132f0 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20         query in 
13300 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 61 6e  process, skip an
13310 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65  y subsequent que
13320 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a 2a 2a  ries, set the.**
13330 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a 52 65            *pazRe
13340 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69 6e  sult output poin
13350 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20  ter to NULL and 
13360 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
13370 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  OMEM]..**.** {H1
13380 32 33 37 33 7d 20 49 66 20 74 68 65 20 70 6e 43  2373} If the pnC
13390 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20  olumn parameter 
133a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  to [sqlite3_get_
133b0 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20  table()] is not 
133c0 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
133d0 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66   then a successf
133e0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
133f0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
13400 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20  ble()] shall.** 
13410 20 20 20 20 20 20 20 20 20 77 72 69 74 65 20 74           write t
13420 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
13430 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  umns in the.**  
13440 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
13450 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
13460 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a  into *pnColumn..
13470 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d 20 49  **.** {H12374} I
13480 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61 72 61  f the pnRow para
13490 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
134a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
134b0 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
134c0 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75         then a su
134d0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
134e0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
134f0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61  get_table()] sha
13500 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ll.**          w
13510 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65 72  rites the number
13520 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a   of rows in the.
13530 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
13540 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
13550 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e  ery into *pnRow.
13560 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36 7d 20  .**.** {H12376} 
13570 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
13580 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
13590 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
135a0 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73 0a 2a   that computes.*
135b0 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72 6f 77  *          N row
135c0 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69 74 68  s of result with
135d0 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 20 72   C columns per r
135e0 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 2a 70  ow shall make *p
135f0 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  azResult.**     
13600 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 61 6e       point to an
13610 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
13620 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 73 74  rs to (N+1)*C st
13630 72 69 6e 67 73 20 77 68 65 72 65 20 74 68 65 20  rings where the 
13640 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
13650 20 20 43 20 73 74 72 69 6e 67 73 20 61 72 65 20    C strings are 
13660 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73 20  column names as 
13670 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
13680 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13690 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
136a0 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74 20 61  ] and the rest a
136b0 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74  re column result
136c0 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
136d0 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f      obtained fro
136e0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
136f0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
13700 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20 76 61   {H12379} The va
13710 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61 7a 52  lues in the pazR
13720 65 73 75 6c 74 20 61 72 72 61 79 20 72 65 74 75  esult array retu
13730 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
13740 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
13750 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
13760 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e 74  remain valid unt
13770 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b 73  il cleared by [s
13780 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
13790 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
137a0 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 72 72  382} When an err
137b0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
137c0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b   evaluation of [
137d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
137e0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
137f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68   the function sh
13800 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73 75  all set *pazResu
13810 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 69 74  lt to NULL, writ
13820 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  e an error messa
13830 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ge.**          i
13840 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
13850 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
13860 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b  3_malloc()], mak
13870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 2a  e.**          **
13880 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 20 74  pzErrmsg point t
13890 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d 65 73  o that error mes
138a0 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75 72 6e  sage, and return
138b0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   a.**          a
138c0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
138d0 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
138e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
138f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
13900 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
13910 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
13920 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
13930 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
13940 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
13950 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
13960 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
13970 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
13980 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
13990 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
139a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
139b0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
139c0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
139d0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
139e0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
139f0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
13a00 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
13a10 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
13a20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
13a30 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
13a40 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
13a50 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
13a60 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
13a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
13a80 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
13a90 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
13aa0 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30   {H17400} <S7000
13ab0 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20000>.**.**
13ac0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
13ad0 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f  are workalikes o
13ae0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
13af0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
13b00 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
13b10 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
13b20 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ary..**.** The s
13b30 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
13b40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
13b50 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
13b60 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
13b70 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
13b80 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
13b90 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13ba0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
13bb0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
13bc0 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
13bd0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
13be0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
13bf0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
13c00 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
13c10 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
13c20 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
13c30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
13c40 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
13c50 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
13c60 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
13c70 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
13c80 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
13c90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
13ca0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
13cb0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
13cc0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
13cd0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
13ce0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
13cf0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
13d00 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
13d10 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
13d20 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
13d30 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
13d40 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
13d50 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
13d60 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
13d70 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
13d80 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
13d90 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
13da0 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
13db0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
13dc0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
13dd0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
13de0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
13df0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
13e00 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
13e10 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
13e20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13e30 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
13e40 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
13e50 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
13e60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13e70 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
13e80 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
13e90 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
13ea0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
13eb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13ec0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
13ed0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
13ee0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
13ef0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
13f00 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
13f10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13f20 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
13f30 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
13f40 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
13f50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
13f60 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
13f70 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
13f80 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
13f90 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
13fa0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
13fb0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
13fc0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
13fd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
13fe0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
13ff0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
14000 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
14010 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
14020 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
14030 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
14040 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
14050 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
14060 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
14070 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
14080 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
14090 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
140a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
140b0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
140c0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
140d0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
140e0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
140f0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
14100 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
14110 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
14120 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
14130 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
14140 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
14150 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
14160 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
14170 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
14180 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
14190 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
141a0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
141b0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
141c0 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
141d0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
141e0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
141f0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
14200 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
14210 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
14220 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
14230 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
14240 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
14250 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
14260 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
14270 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
14280 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
14290 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
142a0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
142b0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
142c0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
142d0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
142e0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
142f0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
14300 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
14310 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
14320 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
14330 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
14340 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
14350 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14360 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
14370 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
14380 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
14390 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
143a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
143b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
143c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
143d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
143e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
143f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
14400 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
14410 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
14420 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
14430 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
14440 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14450 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
14460 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
14470 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
14480 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
14490 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
144a0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
144b0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
144c0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
144d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
144e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
144f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
14500 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
14510 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
14520 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14530 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
14540 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
14550 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
14560 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
14570 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
14580 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
14590 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
145a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
145b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
145c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
145d0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
145e0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
145f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14600 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
14610 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
14620 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
14630 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
14640 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
14650 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
14660 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
14670 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
14680 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
14690 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
146a0 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
146b0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
146c0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
146d0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
146e0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
146f0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
14700 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
14710 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
14720 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
14730 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
14740 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
14750 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
14760 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
14770 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
14780 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20   single quotes) 
14790 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
147a0 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20  %Q option.  So, 
147b0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
147c0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
147d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
147e0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
147f0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
14800 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
14810 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
14820 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
14830 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
14840 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
14850 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
14860 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
14870 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
14890 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
148a0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
148b0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
148c0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
148d0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
148e0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
148f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
14900 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66  **.** The "%z" f
14910 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
14920 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c   works exactly l
14930 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68  ike "%s" with th
14940 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
14950 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
14960 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
14970 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
14980 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
14990 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
149a0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
149b0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
149c0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56   {END}.**.** INV
149d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
149e0 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71  H17403}  The [sq
149f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
14a00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d   and [sqlite3_vm
14a10 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
14a20 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  aces.**         
14a30 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20    return either 
14a40 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
14a50 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
14a60 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69  8 strings held i
14a70 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  n.**           m
14a80 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
14a90 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
14aa0 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70  loc()] or NULL p
14ab0 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20  ointers if.**   
14ac0 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74          a call t
14ad0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
14ae0 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  c()] fails..**.*
14af0 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68 65 20  * {H17406}  The 
14b00 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
14b10 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  f()] interface w
14b20 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72  rites a zero-ter
14b30 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
14b40 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
14b50 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  g into the buffe
14b60 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  r pointed to by 
14b70 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14b80 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
14b90 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20    provided that 
14ba0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14bb0 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74  ter is greater t
14bc0 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  han zero..**.** 
14bd0 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73  {H17407}  The [s
14be0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14bf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
14c00 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f 74  s not write slot
14c10 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
14c20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 66    its output buf
14c30 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20  fer (the second 
14c40 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69  parameter) outsi
14c50 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20  de the range.** 
14c60 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 74            of 0 t
14c70 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72  hrough N-1 (wher
14c80 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 74  e N is the first
14c90 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20   parameter).**  
14ca0 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 6c           regardl
14cb0 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74  ess of the lengt
14cc0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a  h of the string.
14cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 71  **           req
14ce0 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66 6f  uested by the fo
14cf0 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 69  rmat specificati
14d00 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  on..*/.char *sql
14d10 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
14d20 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
14d30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
14d40 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
14d50 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
14d60 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
14d70 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
14d80 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
14d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14da0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14db0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48  ion Subsystem {H
14dc0 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17300} <S20000>.
14dd0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
14de0 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73   core  uses thes
14df0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
14e00 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
14e10 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
14e20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14e30 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
14e40 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
14e50 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
14e60 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
14e70 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
14e80 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
14e90 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
14ea0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
14eb0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
14ec0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
14ed0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
14ee0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
14ef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
14f00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
14f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
14f20 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
14f30 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
14f40 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
14f50 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
14f60 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c  meter..** If sql
14f70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
14f80 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
14f90 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
14fa0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
14fb0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
14fc0 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20  ointer.  If the 
14fd0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
14fe0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
14ff0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
15000 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
15010 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
15020 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
15030 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61  ointer..**.** Ca
15040 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
15050 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
15060 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
15070 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
15080 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
15090 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
150a0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
150b0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
150c0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
150d0 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c  reused.  The sql
150e0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
150f0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
15100 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
15110 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
15120 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
15130 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
15140 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
15150 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
15160 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
15170 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
15180 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
15190 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
151a0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
151b0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
151c0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
151d0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
151e0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
151f0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
15200 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
15210 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
15220 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
15230 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
15240 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
15250 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
15260 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
15270 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
15280 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
15290 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
152a0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
152b0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
152c0 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a  ite3_free()..**.
152d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
152e0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
152f0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
15300 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
15310 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15320 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
15330 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
15340 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
15350 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
15360 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
15370 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
15380 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
15390 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
153a0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
153b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
153c0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
153d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
153e0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
153f0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
15400 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
15410 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
15420 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
15430 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15440 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15450 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
15460 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15470 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15480 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
15490 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
154a0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
154b0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
154c0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
154d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
154e0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
154f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15500 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15510 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
15520 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
15530 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15540 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
15550 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
15560 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
15570 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
15580 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
15590 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
155a0 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
155b0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
155c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
155d0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
155e0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
155f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
15600 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
15610 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
15620 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
15630 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
15640 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
15650 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
15660 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
15670 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15680 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
15690 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
156a0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
156b0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
156c0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
156d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
156e0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
156f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
15700 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
15710 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
15720 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
15730 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
15740 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
15750 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
15760 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15770 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
15780 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
15790 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
157a0 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
157b0 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
157c0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48  C library..** {H
157d0 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
157e0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
157f0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15800 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
15810 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
15820 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15830 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
15840 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
15850 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
15860 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
15870 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
15880 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
15890 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
158a0 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
158b0 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
158c0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
158d0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
158e0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
158f0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
15900 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
15910 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
15920 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
15930 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
15940 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
15950 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
15960 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
15970 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
15980 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
15990 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
159a0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
159b0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
159c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
159d0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
159e0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
159f0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
15a00 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
15a10 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
15a20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
15a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
15a40 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
15a50 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
15a60 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
15a70 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
15a80 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
15a90 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
15aa0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
15ab0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
15ac0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
15ad0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
15ae0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
15af0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
15b00 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
15b10 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
15b20 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
15b30 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
15b40 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
15b50 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
15b60 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
15b70 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
15b80 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
15b90 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
15ba0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
15bb0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
15bc0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
15bd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15be0 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65  ** {H17303}  The
15bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15c00 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
15c10 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
15c20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
15c30 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20          a newly 
15c40 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63  checked-out bloc
15c50 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  k of at least N 
15c60 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  bytes of memory.
15c70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
15c80 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
15c90 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72  ned, or it retur
15ca0 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73  ns NULL if it is
15cb0 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20   unable.**      
15cc0 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20       to fulfill 
15cd0 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a  the request..**.
15ce0 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65  ** {H17304}  The
15cf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15d00 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
15d10 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
15d20 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20  inter if.**     
15d30 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20        N is less 
15d40 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
15d50 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   zero..**.** {H1
15d60 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69  7305}  The [sqli
15d70 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74  te3_free(P)] int
15d80 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20  erface releases 
15d90 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c  memory previousl
15da0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  y.**           r
15db0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
15dc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
15dd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
15de0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
15df0 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61       making it a
15e00 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75  vailable for reu
15e10 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30  se..**.** {H1730
15e20 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  6}  A call to [s
15e30 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c  qlite3_free(NULL
15e40 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  )] is a harmless
15e50 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48   no-op..**.** {H
15e60 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74  17310}  A call t
15e70 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
15e80 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69  oc(0,N)] is equi
15e90 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
15ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
15eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15ec0 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  (N)]..**.** {H17
15ed0 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  312}  A call to 
15ee0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15ef0 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
15f00 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
15f10 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
15f20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
15f30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d  ..**.** {H17315}
15f40 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
15f50 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  e uses [sqlite3_
15f60 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
15f70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
15f80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64  **           and
15f90 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15fa0 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  ] for all of its
15fb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15fc0 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
15fd0 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e      deallocation
15fe0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   needs..**.** {H
15ff0 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
16000 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
16010 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
16020 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
16030 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
16040 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66     to a block of
16050 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d   checked-out mem
16060 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
16070 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a  N bytes in size.
16080 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
16090 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
160a0 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ned, or a NULL p
160b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
160c0 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71  17321}  When [sq
160d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
160e0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
160f0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
16100 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
16110 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65        copies the
16120 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f   first K bytes o
16130 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50  f content from P
16140 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a   into the newly.
16150 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c  **           all
16160 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68  ocated block, wh
16170 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73  ere K is the les
16180 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65  ser of N and the
16190 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20   size of.**     
161a0 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72        the buffer
161b0 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32   P..**.** {H1732
161c0 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  2}  When [sqlite
161d0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
161e0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
161f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
16200 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
16210 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62    releases the b
16220 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
16230 48 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73  H17323}  When [s
16240 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
16250 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c  ,N)] returns NUL
16260 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20  L, the buffer P 
16270 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  is.**           
16280 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20  not modified or 
16290 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
162a0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
162b0 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65  ** {A17350}  The
162c0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
162d0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
162e0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
162f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
16300 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  *           must
16310 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
16320 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
16330 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
16340 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
16350 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f      invocation o
16360 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
16370 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16380 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
16390 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
163a0 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20     not yet been 
163b0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
163c0 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20 61 70  {A17351}  The ap
163d0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
163e0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
163f0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
16400 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63            a bloc
16410 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
16420 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
16430 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
16440 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16450 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
16460 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16470 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
16480 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
16490 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
164a0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
164b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
164c0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
164d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
164e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
164f0 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33  Statistics {H173
16500 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a  70} <S30210>.**.
16510 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
16520 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
16530 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
16540 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
16550 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
16560 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16570 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
16580 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
16590 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
165a0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
165b0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
165c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
165d0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
165e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
165f0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54  **.** {H17371} T
16600 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
16610 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
16620 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
16630 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
16640 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65  *          of me
16650 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
16660 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
16670 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
16680 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  ed)..**.** {H173
16690 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
166a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
166b0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
166c0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
166d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
166e0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
166f0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
16700 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
16710 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20  er mark.**      
16720 20 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73      was last res
16730 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  et..**.** {H1737
16740 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65  4} The values re
16750 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16760 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16770 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
16780 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
16790 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
167a0 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
167b0 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ead.**          
167c0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
167d0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
167e0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
167f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
16800 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74           but not
16810 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
16820 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
16830 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
16840 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  rary.**         
16850 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
16860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16870 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
16880 2a 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d  * {H17375} The m
16890 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
168a0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
168b0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
168c0 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
168d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
168e0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
168f0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
16900 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
16910 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16920 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16930 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68  ()] is true.  Th
16940 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
16960 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16970 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
16980 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
16990 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  mark.**         
169a0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
169b0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
169c0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
169d0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
169e0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
169f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16a00 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
16a10 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
16a20 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
16a30 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
16a40 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d  nerator {H17390}
16a50 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
16a60 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
16a70 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
16a80 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
16a90 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
16aa0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
16ab0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f  select random RO
16ac0 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74  WIDs when insert
16ad0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
16ae0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
16af0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
16b00 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
16b10 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54  ssible ROWID.  T
16b20 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
16b30 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
16b40 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
16b50 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
16b60 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
16b70 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
16b80 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
16b90 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
16ba0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
16bb0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
16bc0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
16bd0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
16be0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
16bf0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
16c00 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
16c10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
16c20 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
16c30 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
16c40 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
16c50 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
16c60 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
16c70 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
16c80 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
16c90 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
16ca0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
16cb0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
16cc0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
16cd0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
16ce0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
16cf0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
16d00 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
16d10 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
16d20 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
16d30 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
16d40 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16d50 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
16d60 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
16d70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
16d80 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68  *.** {H17392} Th
16d90 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  e [sqlite3_rando
16da0 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65  mness(N,P)] inte
16db0 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
16dc0 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
16dd0 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79      high-quality
16de0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
16df0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
16e00 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
16e10 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
16e20 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
16e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
16e40 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
16e50 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
16e60 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37  cks {H12500} <S7
16e70 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0100>.**.** This
16e80 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
16e90 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
16ea0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
16eb0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
16ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16ed0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
16ee0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16ef0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
16f00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16f10 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
16f20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
16f30 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
16f40 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
16f50 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
16f60 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
16f70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
16f80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
16f90 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
16fa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
16fb0 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
16fc0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
16fd0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
16fe0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
16ff0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
17000 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
17010 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
17020 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
17030 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17040 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
17050 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
17060 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
17070 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
17080 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
17090 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
170a0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
170b0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
170c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
170d0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
170e0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
170f0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
17100 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
17110 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
17120 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
17130 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
17140 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
17150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
17160 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
17170 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
17180 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
17190 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
171a0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
171b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
171c0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
171d0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
171e0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
171f0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
17200 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
17210 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
17220 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
17230 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
17240 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
17250 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
17260 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
17270 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17280 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
17290 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
172a0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
172b0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
172c0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
172d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
172e0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
172f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17300 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
17310 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
17320 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
17330 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
17340 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
17350 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
17360 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
17370 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49  ss is denied.  I
17380 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
17390 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
173a0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
173b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
173c0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
173d0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
173e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
173f0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
17400 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
17410 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
17420 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
17430 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
17440 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
17450 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
17460 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
17470 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
17480 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
17490 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
174a0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
174b0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
174c0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
174d0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
174e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
174f0 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   table..**.** Th
17500 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17510 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17520 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17530 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
17540 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
17550 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
17560 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17570 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20   interface. The 
17580 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17590 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
175a0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
175b0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
175c0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
175d0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
175e0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
175f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
17600 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72  orized. The thir
17610 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
17620 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
17630 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
17640 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
17650 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
17660 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
17670 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
17680 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
17690 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
176a0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
176b0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
176c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
176d0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
176e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
176f0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
17700 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
17710 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
17720 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
17730 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
17740 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
17750 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
17760 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
17770 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
17780 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
17790 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
177a0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
177b0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
177c0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
177d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
177e0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
177f0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
17800 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
17810 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
17820 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
17830 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
17840 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
17850 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
17860 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
17870 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
17880 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
17890 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
178a0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
178b0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
178c0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
178d0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
178e0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
178f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
17900 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
17910 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
17920 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
17930 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
17940 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
17950 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
17960 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
17970 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
17980 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
17990 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
179a0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
179b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
179c0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
179d0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
179e0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
179f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
17a00 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
17a10 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
17a20 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
17a30 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
17a40 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
17a50 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
17a60 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
17a70 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
17a80 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
17a90 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
17aa0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
17ab0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
17ac0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
17ad0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
17ae0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
17af0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
17b00 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
17b10 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
17b20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
17b30 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * When [sqlite3_
17b40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
17b50 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
17b60 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
17b70 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
17b80 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61 72  ight be reprepar
17b90 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
17ba0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
17bb0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
17bc0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
17bd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
17be0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
17bf0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
17c00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17c10 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
17c20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
17c30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17c40 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  ]..**.** Note th
17c50 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
17c60 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
17c70 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
17c80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
17c90 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
17ca0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
17cb0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
17cc0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
17cd0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
17ce0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
17cf0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
17d00 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
17d10 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54  **.** {H12501} T
17d20 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17d30 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e  authorizer(D,...
17d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
17d50 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20  isters a.**     
17d60 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
17d70 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61  callback with da
17d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17d90 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  n D..**.** {H125
17da0 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a  02} The authoriz
17db0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
17dc0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
17dd0 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
17de0 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 70           being p
17df0 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 69  arseed and compi
17e00 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  led..**.** {H125
17e10 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  03} If the autho
17e20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
17e30 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65  eturns any value
17e40 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
17e50 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
17e60 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
17e70 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
17e80 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20  _DENY], then.** 
17e90 20 20 20 20 20 20 20 20 20 74 68 65 20 61 70 70           the app
17ea0 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61  lication interfa
17eb0 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75  ce call that cau
17ec0 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sed.**          
17ed0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17ee0 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73  allback to run s
17ef0 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  hall fail with a
17f00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
17f10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72  QLITE_ERROR] err
17f20 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61  or code and an a
17f30 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
17f40 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
17f50 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68  {H12504} When th
17f60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17f70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
17f80 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f  QLITE_OK], the o
17f90 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  peration.**     
17fa0 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69       described i
17fb0 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d  s processed norm
17fc0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ally..**.** {H12
17fd0 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75  505} When the au
17fe0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17ff0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
18000 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
18010 20 20 20 20 20 20 20 20 20 61 70 70 6c 69 63 61           applica
18020 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63  tion interface c
18030 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20  all that caused 
18040 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
18050 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18060 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
18070 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20   fail.**        
18080 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54    with an [SQLIT
18090 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
180a0 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ode and an error
180b0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
180c0 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20       explaining 
180d0 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64  that access is d
180e0 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  enied..**.** {H1
180f0 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74  2506} If the aut
18100 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
18110 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
18120 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
18130 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
18140 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49  llback) is [SQLI
18150 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65  TE_READ] and the
18160 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18170 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
18180 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
18190 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74  _IGNORE], then t
181a0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
181b0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
181c0 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  cted to.**      
181d0 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c      insert a NUL
181e0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
181f0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
18200 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
18210 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
18220 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
18230 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
18240 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  en returned..**.
18250 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74  ** {H12507} If t
18260 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
18270 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
18280 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
18290 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
182a0 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
182b0 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20   anything other 
182c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41  than [SQLITE_REA
182d0 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  D], then.**     
182e0 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66       a return of
182f0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18300 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66   has the same ef
18310 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f  fect as [SQLITE_
18320 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DENY]..**.** {H1
18330 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20  2510} The first 
18340 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18350 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18360 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
18370 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
18380 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
18390 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
183a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
183b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
183c0 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68  *.** {H12511} Th
183d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
183e0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
183f0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
18400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
18410 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
18420 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
18430 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74  ecifies the part
18440 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a  icular action.**
18450 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20            to be 
18460 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
18470 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74  * {H12512} The t
18480 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
18490 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
184a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
184b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
184c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
184d0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
184e0 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  in.**          a
184f0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
18500 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
18510 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
18520 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  zed..**.** {H125
18530 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  20} Each call to
18540 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18550 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72  thorizer()] over
18560 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  rides.**        
18570 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79    any previously
18580 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f   installed autho
18590 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rizer..**.** {H1
185a0 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74  2521} A NULL aut
185b0 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68  horizer means th
185c0 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74  at no authorizat
185d0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
185e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
185f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ked..**.** {H125
18600 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  22} The default 
18610 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55  authorizer is NU
18620 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
18630 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18640 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
18650 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
18660 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
18670 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
18680 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
18690 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
186a0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
186b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
186c0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
186d0 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d  n Codes {H12590}
186e0 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
186f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
18700 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
18710 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18720 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
18730 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
18740 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
18750 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
18760 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
18770 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
18780 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
18790 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
187a0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
187b0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
187c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
187d0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
187e0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
187f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
18800 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
18810 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18820 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
18830 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
18840 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
18850 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
18860 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
18870 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
18880 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
18890 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
188a0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
188b0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
188c0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
188d0 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35  s {H12550} <H125
188e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  00>.**.** The [s
188f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18900 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
18910 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
18920 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18930 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
18940 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
18950 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
18960 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
18970 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
18980 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18990 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
189a0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
189b0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
189c0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
189d0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
189e0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
189f0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
18a00 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
18a10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18a20 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
18a30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
18a40 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
18a50 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
18a60 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
18a70 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
18a80 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
18a90 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
18aa0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
18ab0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
18ac0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
18ad0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
18ae0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
18af0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
18b00 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
18b10 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
18b20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
18b30 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
18b40 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
18b50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18b60 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
18b70 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
18b80 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
18b90 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
18ba0 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
18bb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
18bc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18bd0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
18be0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
18bf0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
18c00 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
18c10 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
18c20 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18c30 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
18c40 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
18c50 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
18c60 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
18c70 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49  QL code..**.** I
18c80 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
18c90 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 65   {H12551} The se
18ca0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
18cb0 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  o an.**         
18cc0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18cd0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
18ce0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
18cf0 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65  shall be an inte
18d00 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
18d10 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
18d20 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
18d30 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77  that specifies w
18d40 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  hat action.**   
18d50 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20         is being 
18d60 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
18d70 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33  * {H12552} The 3
18d80 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
18d90 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  eters to the.** 
18da0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18db0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18dc0 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e   | authorization
18dd0 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20   callback].**   
18de0 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20         shall be 
18df0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
18e00 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
18e10 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20  which.**        
18e20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
18e30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
18e40 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  ] is used as the
18e50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18e60 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33  r..**.** {H12553
18e70 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  } The 5th parame
18e80 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
18e90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18ea0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
18eb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18ec0 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74  back] shall be t
18ed0 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
18ee0 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62      of the datab
18ef0 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d  ase (example: "m
18f00 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74  ain", "temp", et
18f10 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
18f20 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34  e..**.** {H12554
18f30 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65  } The 6th parame
18f40 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
18f50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18f60 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
18f70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18f80 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74  back] shall be t
18f90 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
18fa0 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72      of the inner
18fb0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
18fc0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
18fd0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
18fe0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63            the ac
18ff0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
19000 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
19010 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
19020 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
19030 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76           top-lev
19040 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
19050 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
19060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
19080 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
19090 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
190a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
190b0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
190c0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
190d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
190e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
190f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19100 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
19110 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
19120 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19130 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19140 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19150 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
19160 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
19170 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19180 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19190 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
191a0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
191b0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
191c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
191d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
191e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
191f0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
19200 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
19210 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19220 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19230 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19240 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
19250 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19260 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19270 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19280 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
19290 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
192a0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
192b0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
192c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
192d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
192e0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
192f0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19300 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19310 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19320 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
19330 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
19340 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19350 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19360 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19370 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
19380 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
19390 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
193a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
193b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
193c0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
193d0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
193e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
193f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19400 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19410 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
19420 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
19430 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
19440 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19450 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19460 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
19470 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
19480 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19490 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
194a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
194b0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
194c0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
194d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
194e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
194f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19500 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
19510 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
19520 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19530 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19540 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19550 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
19560 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
19570 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19580 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19590 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
195a0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
195b0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
195c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
195d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
195e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
195f0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
19600 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
19610 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19620 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19630 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
19640 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
19650 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
19660 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
19670 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
19680 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
19690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
196a0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
196b0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
196c0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
196d0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
196e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
196f0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
19700 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19710 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19720 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
19730 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
19740 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
19750 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19760 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19770 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
19780 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
19790 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
197a0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
197b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
197c0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
197d0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
197e0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
197f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19800 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19810 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
19820 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
19830 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
19840 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19850 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19860 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
19870 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
19880 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
19890 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
198a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
198b0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
198c0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
198d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
198e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
198f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19900 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
19910 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
19920 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19930 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19940 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19950 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
19960 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
19970 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
19980 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19990 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
199a0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
199b0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
199c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
199d0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
199e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
199f0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
19a00 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e       31   /* Fun
19a10 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c  ction Name   NUL
19a20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19a30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19a40 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
19a50 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
19a60 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
19a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
19a80 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
19a90 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ling Functions {
19aa0 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e  H12280} <S60400>
19ab0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
19ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19ad0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
19ae0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19af0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
19b00 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
19b10 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
19b20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
19b30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
19b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
19b50 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
19b60 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
19b70 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
19b80 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
19b90 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
19ba0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
19bb0 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
19bc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19bd0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
19be0 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d  k returns a UTF-
19bf0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
19c00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19c10 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20   text.** as the 
19c20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
19c30 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
19c40 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61  .  Additional ca
19c50 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a  llbacks occur.**
19c60 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
19c70 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
19c80 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
19c90 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
19ca0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
19cb0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
19cc0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
19cd0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
19ce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
19cf0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
19d00 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19d10 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
19d20 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
19d30 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
19d40 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65  t finishes.  The
19d50 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
19d60 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
19d70 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
19d80 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
19d90 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
19da0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
19db0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
19dc0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
19dd0 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  to run..**.** IN
19de0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
19df0 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c  {H12281} The cal
19e00 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19e10 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
19e20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a  lite3_trace()] .
19e30 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
19e40 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
19e50 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
19e60 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  r an SQL stateme
19e70 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
19e80 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a  to execute and.*
19e90 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65  *          whene
19ea0 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75  ver a trigger su
19eb0 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62  bprogram first b
19ec0 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a  egins to run..**
19ed0 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63  .** {H12282} Eac
19ee0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
19ef0 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c  e3_trace()] shal
19f00 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 70  l override the p
19f10 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
19f20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
19f30 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e   trace callback.
19f40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20  .**.** {H12283} 
19f50 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c  A NULL trace cal
19f60 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61  lback shall disa
19f70 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a  ble tracing..**.
19f80 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20  ** {H12284} The 
19f90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19fa0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
19fb0 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20  back shall be a 
19fc0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
19fd0 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20      the pointer 
19fe0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72  which was the 3r
19ff0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  d argument to [s
1a000 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e  qlite3_trace()].
1a010 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20  .**.** {H12285} 
1a020 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1a030 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
1a040 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a   callback is a.*
1a050 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1a060 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a070 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1a080 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
1a090 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
1a0a0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
1a0b0 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20  ement as it was 
1a0c0 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c  passed into [sql
1a0d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a0e0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1a0f0 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
1a100 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  , or an SQL comm
1a110 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ent indicating t
1a120 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  he beginning.** 
1a130 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72           of a tr
1a140 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
1a150 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d  ..**.** {H12287}
1a160 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
1a170 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1a180 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
1a190 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f  ofile()] is invo
1a1a0 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ked.**          
1a1b0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
1a1c0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
1a1d0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54  **.** {H12288} T
1a1e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a1f0 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
1a200 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
1a210 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
1a220 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61      the 3rd para
1a230 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1a240 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a  3_profile()]..**
1a250 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65  .** {H12289} The
1a260 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a270 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
1a280 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a   callback is a.*
1a290 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1a2a0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a2b0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e   string that con
1a2c0 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65  tains the comple
1a2d0 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20  te text of.**   
1a2e0 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73         the SQL s
1a2f0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
1a300 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20  as processed by 
1a310 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a320 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  _v2()].**       
1a330 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61     or the equiva
1a340 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lent..**.** {H12
1a350 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70  290} The third p
1a360 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a370 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1a380 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a   is an estimate.
1a390 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
1a3a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
1a3b0 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c  oseconds of wall
1a3c0 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75  -clock time requ
1a3d0 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ired to.**      
1a3e0 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20      run the SQL 
1a3f0 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73  statement from s
1a400 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a  tart to finish..
1a410 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
1a420 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1a430 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1a440 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1a450 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1a460 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1a470 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1a480 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1a490 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1a4a0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1a4b0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1a4c0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1a4d0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1a4e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a4f0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1a500 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
1a510 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  10} <S60400>.**.
1a520 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1a530 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c  configures a cal
1a540 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d  lback function -
1a550 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73   the.** progress
1a560 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74   callback - that
1a570 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
1a580 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1a590 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  long.** running 
1a5a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1a5b0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1a5c0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a  te3_step()] and.
1a5d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1a5e0 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78  table()].  An ex
1a5f0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1a600 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1a610 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1a620 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1a630 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1a640 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67  *.** If the prog
1a650 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1a660 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1a670 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1a680 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1a690 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1a6a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1a6b0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1a6c0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1a6d0 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78  a GUI dialog box
1a6e0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1a6f0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  TS:.**.** {H1291
1a700 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
1a710 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1a720 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1a730 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1a740 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ).**          is
1a750 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1a760 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1a770 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1a780 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1a790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1a7a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20  .**.** {H12912} 
1a7b0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1a7c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1a7d0 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
1a7e0 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20  N virtual.**    
1a7f0 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70        machine op
1a800 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69  codes, where N i
1a810 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
1a820 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1a830 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
1a840 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1a850 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  er()] call that 
1a860 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
1a870 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62         the callb
1a880 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65  ack.  If N is le
1a890 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74  ss than 1, sqlit
1a8a0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a8b0 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
1a8c0 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e    acts as if a N
1a8d0 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e  ULL progress han
1a8e0 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70  dler had been sp
1a8f0 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ecified..**.** {
1a900 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67  H12913} The prog
1a910 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
1a920 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
1a930 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
1a940 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
1a950 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1a960 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1a970 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ()..**.** {H1291
1a980 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  4} The fourth ar
1a990 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1a9a0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1a9b0 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20  er() is a.**    
1a9c0 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74        void point
1a9d0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
1a9e0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1a9f0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ck.**          f
1aa00 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
1aa10 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
1aa20 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20  .**.** {H12915} 
1aa30 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
1aa40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
1aa50 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
1aa60 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a  han N opcodes.**
1aa70 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
1aa80 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74  executed, then t
1aa90 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1aaa0 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
1aab0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1aac0 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c  2916} Every call
1aad0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
1aae0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1aaf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1ab00 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76  rwrites any prev
1ab10 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
1ab20 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  d progress handl
1ab30 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  er..**.** {H1291
1ab40 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  7} If the progre
1ab50 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1ab60 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ack is NULL then
1ab70 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20   no progress.** 
1ab80 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72           handler
1ab90 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
1aba0 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74  ** {H12918} If t
1abb0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1abc0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72  back returns a r
1abd0 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e  esult other than
1abe0 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   0, then.**     
1abf0 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f       the behavio
1ac00 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74  r is a if [sqlit
1ac10 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
1ac20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  had been called.
1ac30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33  .**          <S3
1ac40 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71  0500>.*/.void sq
1ac50 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1ac60 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1ac70 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1ac80 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1ac90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1aca0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1acb0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
1acc0 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
1acd0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1ace0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1acf0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1ad00 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1ad10 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1ad20 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1ad30 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
1ad40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1ad50 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1ad60 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1ad70 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1ad80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1ad90 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1ada0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1adb0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1adc0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
1add0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ade0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1adf0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1ae00 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1ae10 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1ae20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1ae30 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1ae40 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1ae50 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1ae60 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1ae70 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1ae80 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1ae90 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1aea0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1aeb0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1aec0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1aed0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1aee0 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
1aef0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1af00 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1af10 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1af20 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1af30 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1af40 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1af50 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1af60 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
1af70 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1af80 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1af90 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1afa0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1afb0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1afc0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1afd0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1afe0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
1aff0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1b000 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1b010 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1b020 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1b030 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1b040 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1b050 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1b060 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1b070 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1b080 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1b090 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1b0a0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1b0b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1b0c0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1b0d0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1b0e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1b0f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1b100 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1b110 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1b120 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1b130 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1b140 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1b150 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1b160 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1b170 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b180 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1b190 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1b1a0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1b1b0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1b1c0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1b1d0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1b1e0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1b1f0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1b200 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1b210 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
1b220 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
1b230 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1b240 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1b250 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1b260 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1b270 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1b280 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1b290 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20 3c 64  ] flag:.**.** <d
1b2a0 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  l>.** <dt>[SQLIT
1b2b0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1b2c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b2d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1b2e0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1b2f0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1b300 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1b310 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1b320 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1b330 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
1b340 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1b350 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1b360 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b370 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1b380 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1b390 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1b3a0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1b3b0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1b3c0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1b3d0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1b3e0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1b3f0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1b400 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1b410 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1b420 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1b430 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1b440 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  urned.</dd>.**.*
1b450 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
1b460 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
1b470 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1b480 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
1b490 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1b4a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1b4b0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
1b4c0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20   and is creates 
1b4d0 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  it if.** it does
1b4e0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
1b4f0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
1b500 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
1b510 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
1b520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1b530 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1b540 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a  pen16().</dd>.**
1b550 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1b560 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1b570 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1b580 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1b590 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1b5a0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1b5b0 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74  bove or one of t
1b5c0 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  he combinations 
1b5d0 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62  shown above comb
1b5e0 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ined.** with the
1b5f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b600 4d 55 54 45 58 5d 20 66 6c 61 67 2c 20 74 68 65  MUTEX] flag, the
1b610 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1b620 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1b630 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54  ** If the [SQLIT
1b640 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1b650 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
1b660 6e 20 6d 75 74 65 78 65 73 20 6f 6e 20 74 68 65  n mutexes on the
1b670 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b 64 61 74 61  .** opened [data
1b680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b690 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e   are disabled an
1b6a0 64 20 74 68 65 20 61 70 70 6c 69 61 74 69 6f 6e  d the appliation
1b6b0 20 6d 75 73 74 0a 2a 2a 20 69 6e 73 75 72 65 20   must.** insure 
1b6c0 74 68 61 74 20 61 63 63 65 73 73 20 74 6f 20 74  that access to t
1b6d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1b6e0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 69 74 73  nection] and its
1b6f0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 5b   associated.** [
1b700 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b710 6e 74 73 5d 20 69 73 20 73 65 72 69 61 6c 69 7a  nts] is serializ
1b720 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1b730 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1b740 6c 61 67 0a 2a 2a 20 69 73 20 74 68 65 20 64 65  lag.** is the de
1b750 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1b760 73 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6e 66  s SQLite is conf
1b770 69 67 75 72 65 64 20 75 73 69 6e 67 20 74 68 65  igured using the
1b780 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
1b790 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 20  IG_MULTITHREAD] 
1b7a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1b7b0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
1b7c0 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 5b 73  options.** to [s
1b7d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1b7e0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
1b7f0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1b800 67 20 6f 6e 6c 79 20 6d 61 6b 65 73 20 61 0a 2a  g only makes a.*
1b810 2a 20 64 69 66 66 65 72 65 6e 63 65 20 77 68 65  * difference whe
1b820 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 69  n SQLite is in i
1b830 74 73 20 64 65 66 61 75 6c 74 20 5b 53 51 4c 49  ts default [SQLI
1b840 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
1b850 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a 0a 2a  IZED] mode..**.*
1b860 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
1b870 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1b880 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1b890 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1b8a0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1b8b0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1b8c0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1b8d0 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20   This in-memory 
1b8e0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1b8f0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1b900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b910 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1b920 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1b930 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1b940 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1b950 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1b960 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1b970 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1b980 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1b990 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1b9a0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1b9b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1b9c0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1b9d0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1b9e0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1b9f0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1ba00 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1ba10 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1ba20 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1ba30 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1ba40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1ba50 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1ba60 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1ba70 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1ba80 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1ba90 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1baa0 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73  e created.  This
1bab0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1bac0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1bad0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1bae0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1baf0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1bb00 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1bb10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
1bb20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1bb30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1bb40 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1bb50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1bb60 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
1bb70 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
1bb80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1bb90 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
1bba0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1bbb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
1bbc0 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20  ld use.  If the 
1bbd0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1bbe0 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1bbf0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1bc00 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1bc10 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1bc20 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  sed..**.** <b>No
1bc30 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1bc40 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1bc50 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1bc60 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1bc70 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1bc80 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1bc90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1bca0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1bcb0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1bcc0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1bcd0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1bce0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1bcf0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1bd00 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1bd10 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1bd20 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1bd30 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1bd40 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1bd50 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1bd60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1bd70 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1bd80 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20  .**.** {H12701} 
1bd90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1bda0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1bdb0 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1bdc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1bdd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1bde0 74 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20  terfaces create 
1bdf0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1be00 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
1be10 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  ection] associat
1be20 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ed with.**      
1be30 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65      the database
1be40 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74   file given in t
1be50 68 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d  heir first param
1be60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
1be70 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d  702} The filenam
1be80 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1be90 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1bea0 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  -8.**          f
1beb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1bec0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1bed0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
1bee0 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  as UTF-16.**    
1bef0 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
1bf00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
1bf10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1bf20 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
1bf30 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66  2703} A successf
1bf40 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
1bf50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1bf60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1bf70 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1bf80 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1bf90 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73  pen_v2()] writes
1bfa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1bfb0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1bfc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bfd0 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62  tion] into *ppDb
1bfe0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d  ..**.** {H12704}
1bff0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1c000 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1c010 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1c020 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c030 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1c040 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1c050 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f   [SQLITE_OK] upo
1c060 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20  n success,.**   
1c070 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70         or an app
1c080 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
1c090 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65  code] on failure
1c0a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d  ..**.** {H12706}
1c0b0 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
1c0c0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
1c0d0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
1c0e0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
1c0f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c100 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
1c110 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1c120 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a  will be UTF-8..*
1c130 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68  *.** {H12707} Th
1c140 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65  e default text e
1c150 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65  ncoding for a ne
1c160 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  w database creat
1c170 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
1c180 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1c190 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20  en16()] will be 
1c1a0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48  UTF-16..**.** {H
1c1b0 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  12709} The [sqli
1c1c0 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69  te3_open(F,D)] i
1c1d0 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69  nterface is equi
1c1e0 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  valent to.**    
1c1f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1c200 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d  pen_v2(F,D,G,0)]
1c210 20 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72   where the G par
1c220 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
1c230 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50        [SQLITE_OP
1c240 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53  EN_READWRITE]|[S
1c250 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1c260 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  E]..**.** {H1271
1c270 31 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  1} If the G para
1c280 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1c290 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1c2a0 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1c2b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1c2c0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1c2d0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68  PEN_READONLY] th
1c2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1c2f0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
1c300 20 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e        for readin
1c310 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g only..**.** {H
1c320 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20  12712} If the G 
1c330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1c340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1c350 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1c360 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1c370 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1c380 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1c390 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  E] then the data
1c3a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a  base is opened.*
1c3b0 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69  *          readi
1c3c0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1c3d0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66  f possible, or f
1c3e0 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
1c3f0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
1c400 20 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65     file is write
1c410 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1c420 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1c430 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  em..**.** {H1271
1c440 33 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  3} If the G para
1c450 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1c460 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1c470 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a  V)] omits the.**
1c480 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1c490 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1c4a0 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65  _CREATE] and the
1c4b0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1c4c0 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ot.**          p
1c4d0 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
1c4e0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1c4f0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  urned..**.** {H1
1c500 32 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70  2714} If the G p
1c510 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1c530 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1c540 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c550 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1c560 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
1c570 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
1c580 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
1c590 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
1c5a0 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61  exist, then an a
1c5b0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1c5c0 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20  o create and.** 
1c5d0 20 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c           initial
1c5e0 69 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ize the database
1c5f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d  ..**.** {H12717}
1c600 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1c610 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1c620 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1c630 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1c640 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
1c650 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1c660 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72  v2()] is ":memor
1c670 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
1c680 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
1c690 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d    ephemeral, in-
1c6a0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1c6b0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1c6c0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  he connection..*
1c6d0 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1c6e0 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >Is SQLITE_OPEN_
1c6f0 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50  CREATE|SQLITE_OP
1c700 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71  EN_READWRITE req
1c710 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  uired.**        
1c720 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65    in sqlite3_ope
1c730 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a  n_v2()?</todo>.*
1c740 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66  *.** {H12719} If
1c750 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1c760 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
1c770 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1c780 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1c790 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20        ephemeral 
1c7a0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1c7b0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1c7c0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1c7d0 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
1c7e0 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
1c7f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1c800 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
1c810 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
1c820 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
1c830 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d  >.**.** {H12721}
1c840 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
1c850 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74  onnection] creat
1c860 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f  ed by [sqlite3_o
1c870 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1c880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
1c890 6c 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  l use the [sqlit
1c8a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1c8b0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
1c8c0 20 56 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a   V parameter,.**
1c8d0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
1c8e0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1c8f0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66  3_vfs] object if
1c900 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
1c910 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nter..**.** {H12
1c920 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61  723} Two [databa
1c930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
1c940 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d  will share a com
1c950 6d 6f 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74  mon cache if bot
1c960 68 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20  h were.**       
1c970 20 20 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74     opened with t
1c980 68 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c  he same VFS whil
1c990 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1c9a0 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65  mode] was enable
1c9b0 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  d and.**        
1c9c0 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61    if both filena
1c9d0 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61  mes compare equa
1c9e0 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29  l using memcmp()
1c9f0 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65   after having be
1ca00 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  en.**          p
1ca10 72 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20  rocessed by the 
1ca20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78  [sqlite3_vfs | x
1ca30 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65  FullPathname] me
1ca40 74 68 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e  thod of the VFS.
1ca50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ca60 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
1ca70 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1ca80 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1ca90 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1caa0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1cab0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1cac0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1cad0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1cae0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1caf0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1cb00 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1cb10 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1cb20 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1cb30 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1cb40 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1cb50 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1cb60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1cb70 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
1cb80 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1cb90 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1cba0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1cbb0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1cbc0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
1cbd0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1cbe0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
1cbf0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
1cc00 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
1cc10 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
1cc20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1cc30 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
1cc40 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
1cc50 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
1cc60 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
1cc70 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30  es {H12800} <S60
1cc80 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200>.**.** The s
1cc90 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1cca0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1ccb0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1ccc0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1ccd0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1cce0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1ccf0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1cd00 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1cd10 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1cd20 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1cd30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd40 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1cd50 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1cd60 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1cd70 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1cd80 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1cd90 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1cda0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1cdb0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1cdc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1cdd0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1cde0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1cdf0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1ce00 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1ce10 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1ce20 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1ce30 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1ce40 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1ce50 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  ively..** Memory
1ce60 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1ce70 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1ce80 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1ce90 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1cea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1ceb0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1cec0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1ced0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1cee0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1cef0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1cf00 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1cf10 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1cf20 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1cf30 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1cf40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1cf50 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
1cf60 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
1cf70 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
1cf80 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
1cf90 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
1cfa0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
1cfb0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
1cfc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1cfd0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
1cfe0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
1cff0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
1d000 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
1d010 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   set..**.** INVA
1d020 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1d030 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12801} The [sqli
1d040 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20  te3_errcode(D)] 
1d050 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1d060 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
1d070 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c            [resul
1d080 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  t code] or [exte
1d090 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1d0a0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
1d0b0 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20  ecently.**      
1d0c0 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72      failed inter
1d0d0 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69  face call associ
1d0e0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d100 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
1d110 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2803} The [sqlit
1d120 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e  e3_errmsg(D)] an
1d130 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
1d140 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20  g16(D)].**      
1d150 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
1d160 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1d170 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74  nguage text that
1d180 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20   describes.**   
1d190 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72         the error
1d1a0 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72   in the mostly r
1d1b0 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69  ecently failed i
1d1c0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a  nterface call,.*
1d1d0 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64  *          encod
1d1e0 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ed as either UTF
1d1f0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1d200 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
1d210 20 7b 48 31 32 38 30 37 7d 20 54 68 65 20 73 74   {H12807} The st
1d220 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1d230 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
1d240 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
1d250 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
1d260 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
1d270 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
1d280 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  xt SQLite interf
1d290 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ace call..**.** 
1d2a0 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74  {H12808} Calls t
1d2b0 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
1d2c0 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
1d2d0 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a  n an error code.
1d2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61  **          (exa
1d2f0 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
1d300 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
1d310 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1d320 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
1d330 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67  r code or messag
1d340 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1d350 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1d360 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1d370 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1d380 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1d390 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
1d3a0 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72  * {H12809} Inter
1d3b0 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
1d3c0 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
1d3d0 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
1d3e0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1d3f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d400 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
1d410 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1d420 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
1d430 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1d440 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
1d450 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
1d460 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1d470 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
1d480 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1d490 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
1d4a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1d4b0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
1d4c0 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
1d4d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
1d4e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1d4f0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1d500 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1d510 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1d520 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1d530 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1d540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d550 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1d560 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c  bject {H13000} <
1d570 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f  H13010>.** KEYWO
1d580 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
1d590 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
1d5a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
1d5b0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1d5c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
1d5d0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
1d5e0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
1d5f0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
1d600 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
1d610 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
1d620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
1d630 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
1d640 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
1d650 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
1d660 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
1d670 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
1d680 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
1d690 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
1d6a0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1d6b0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
1d6c0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
1d6d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d6e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d6f0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
1d700 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
1d710 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
1d720 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
1d730 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
1d740 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1d750 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
1d760 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
1d770 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
1d780 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1d790 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
1d7a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1d7b0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
1d7c0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1d7d0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
1d7e0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
1d7f0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
1d800 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
1d810 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1d820 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
1d830 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1d840 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
1d850 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1d860 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
1d870 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
1d880 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
1d890 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
1d8a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1d8b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1d8c0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
1d8d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
1d8e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1d8f0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b  un-time Limits {
1d900 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e  H12760} <S20600>
1d910 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1d920 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1d930 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1d940 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1d950 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1d960 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1d970 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1d980 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1d990 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1d9a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d9b0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1d9c0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1d9d0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1d9e0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1d9f0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1da00 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1da10 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1da20 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1da30 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1da40 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1da50 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1da60 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1da70 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1da80 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65   construct.  The
1da90 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1daa0 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e  s the old limit.
1dab0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65  .**.** If the ne
1dac0 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
1dad0 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
1dae0 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
1daf0 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  nged..** For the
1db00 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
1db10 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  of SQLITE_LIMIT_
1db20 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68  XYZ there is a h
1db30 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75  ard upper.** bou
1db40 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  nd set by a comp
1db50 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
1db60 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
1db70 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  med SQLITE_MAX_X
1db80 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  YZ..** (The "_LI
1db90 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
1dba0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
1dbb0 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74  "_MAX_".).** Att
1dbc0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1dbd0 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1dbe0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1dbf0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1dc00 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1dc10 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1dc20 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75   limit..**.** Ru
1dc30 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n time limits ar
1dc40 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1dc50 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1dc60 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1dc70 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1dc80 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1dc90 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1dca0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1dcb0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1dcc0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1dcd0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1dce0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1dcf0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1dd00 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61  * webbrowser tha
1dd10 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
1dd20 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
1dd30 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
1dd40 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
1dd50 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
1dd60 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
1dd70 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
1dd80 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
1dd90 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
1dda0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1ddb0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
1ddc0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
1ddd0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
1dde0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
1ddf0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
1de00 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
1de10 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
1de20 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
1de30 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
1de40 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
1de50 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
1de60 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
1de70 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
1de80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
1de90 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
1dea0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
1deb0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
1dec0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
1ded0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
1dee0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
1def0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
1df00 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
1df10 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
1df20 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
1df30 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1df40 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
1df50 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
1df60 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
1df70 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
1df80 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  leases..**.** IN
1df90 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1dfa0 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 65  {H12762} A succe
1dfb0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1dfc0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1dfd0 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a  ,V)] where V is.
1dfe0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69  **          posi
1dff0 74 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65  tive changes the
1e000 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69   limit on the si
1e010 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20  ze of construct 
1e020 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  C in the.**     
1e030 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1e040 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20  onnection] D to 
1e050 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20  the lesser of V 
1e060 61 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70  and the hard upp
1e070 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  er.**          b
1e080 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65  ound on the size
1e090 20 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65   of C that is se
1e0a0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1e0b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36  e..**.** {H12766
1e0c0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1e0d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1e0e0 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68  limit(D,C,V)] wh
1e0f0 65 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76  ere V is negativ
1e100 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65  e.**          le
1e110 61 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f  aves the state o
1e120 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
1e130 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e  connection] D un
1e140 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
1e150 48 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73  H12769} A succes
1e160 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1e170 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1e180 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a  V)] returns the.
1e190 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
1e1a0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f  e of the limit o
1e1b0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
1e1c0 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65  nstruct C in the
1e1d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1e1e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e1f0 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70  n] D as it was p
1e200 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
1e210 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1e220 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
1e230 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
1e240 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
1e250 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1e260 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
1e270 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36   {H12790} <H1276
1e280 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1e290 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1e2a0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   {limit categori
1e2b0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1e2c0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1e2d0 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73   various aspects
1e2e0 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   of a [database 
1e2f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
1e300 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74  hat can be limit
1e310 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61  ed in size by ca
1e320 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1e330 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
1e340 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
1e350 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
1e360 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
1e370 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
1e380 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
1e390 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e3a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
1e3b0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
1e3c0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
1e3d0 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a  e row.<dd>.**.**
1e3e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e3f0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
1e400 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e410 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
1e420 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1e430 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e440 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1e450 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
1e460 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e470 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1e480 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
1e490 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
1e4a0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1e4b0 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d   SELECT or the m
1e4c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1e4d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
1e4e0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
1e4f0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
1e500 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
1e510 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1e520 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1e530 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
1e540 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
1e550 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
1e560 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
1e570 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ession.</dd>.**.
1e580 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1e590 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1e5a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1e5b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e5c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1e5d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1e5e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1e5f0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e600 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
1e610 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e620 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e630 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
1e640 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
1e650 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
1e660 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1e670 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1e680 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1e690 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1e6a0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1e6b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e6c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1e6d0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1e6e0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
1e6f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e700 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
1e710 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e720 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74  mum number of at
1e730 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
1e740 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1e750 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
1e760 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1e770 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1e780 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1e790 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
1e7a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1e7b0 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20  LIKE or.** GLOB 
1e7c0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a  operators.</dd>.
1e7d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e7e0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1e7f0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1e800 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e810 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1e820 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1e830 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1e840 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1e850 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1e860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e870 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
1e880 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
1e890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e8a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
1e8b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
1e8c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e8d0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
1e8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1e8f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e900 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1e910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e920 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
1e930 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1e940 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1e950 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1e960 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
1e970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e980 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
1e990 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1e9a0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
1e9b0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
1e9c0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1e9d0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
1e9e0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
1e9f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1ea00 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
1ea10 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
1ea20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1ea30 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
1ea40 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43        9../*.** C
1ea50 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1ea60 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1ea70 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31  ent {H13010} <S1
1ea80 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0000>.** KEYWORD
1ea90 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
1eaa0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
1eab0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
1eac0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
1ead0 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
1eae0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
1eaf0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
1eb00 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
1eb10 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
1eb20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1eb30 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
1eb40 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1eb50 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
1eb60 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
1eb70 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
1eb80 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1eb90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1eba0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1ebb0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
1ebc0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1ebd0 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1ebe0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1ebf0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1ec00 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1ec10 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1ec20 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1ec30 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1ec40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ec50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1ec60 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1ec70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1ec80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1ec90 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1eca0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1ecb0 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  * If the nByte a
1ecc0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
1ecd0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
1ece0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1ecf0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
1ed00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1ed10 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e   If nByte is non
1ed20 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1ed30 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1ed40 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
1ed50 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1ed60 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74  zSql.  When nByt
1ed70 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1ed80 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
1ed90 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
1eda0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
1edb0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
1edc0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
1edd0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
1ede0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
1edf0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
1ee00 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
1ee10 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
1ee20 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
1ee30 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
1ee40 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
1ee50 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
1ee60 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
1ee70 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
1ee80 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
1ee90 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
1eea0 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
1eeb0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1eec0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
1eed0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
1eee0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
1eef0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
1ef00 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c  s..**.** *pzTail
1ef10 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1ef20 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
1ef30 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64  yte past the end
1ef40 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1ef50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1ef60 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
1ef70 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d  outines only com
1ef80 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a  pile the first.*
1ef90 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  * statement in z
1efa0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
1efb0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1efc0 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73   to what remains
1efd0 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  .** uncompiled..
1efe0 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73  **.** *ppStmt is
1eff0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1f000 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1f010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f020 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1f030 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1f040 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f050 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61  .  If there is a
1f060 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
1f070 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
1f080 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
1f090 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1f0a0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1f0b0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
1f0c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
1f0d0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1f0e0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1f0f0 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38  NULL..** {A13018
1f100 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  } The calling pr
1f110 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1f120 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1f130 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1f140 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1f150 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1f160 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1f170 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1f180 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a  ed with it..**.*
1f190 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
1f1a0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1f1b0 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65  urned, otherwise
1f1c0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1f1d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1f1e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1f1f0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
1f200 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f210 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
1f220 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
1f230 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
1f240 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
1f250 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
1f260 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
1f270 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
1f280 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1f290 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
1f2a0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
1f2b0 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
1f2c0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
1f2d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f2e0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
1f2f0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
1f300 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1f310 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
1f320 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
1f330 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
1f340 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
1f350 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f360 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
1f370 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65  behave a differe
1f380 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73  ntly in two ways
1f390 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1f3a0 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64  <li>.** If the d
1f3b0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
1f3c0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
1f3d0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
1f3e0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
1f3f0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
1f400 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
1f410 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
1f420 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1f430 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
1f440 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
1f450 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
1f460 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68  ain.  If the sch
1f470 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20  ema has changed 
1f480 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74  in.** a way that
1f490 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65   makes the state
1f4a0 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76  ment no longer v
1f4b0 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  alid, [sqlite3_s
1f4c0 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c  tep()] will stil
1f4d0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
1f4e0 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75  ITE_SCHEMA].  Bu
1f4f0 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67  t unlike the leg
1f500 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53  acy behavior, [S
1f510 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73  QLITE_SCHEMA] is
1f520 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20  .** now a fatal 
1f530 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20  error.  Calling 
1f540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f550 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c  _v2()] again wil
1f560 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a  l not make the.*
1f570 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e  * error go away.
1f580 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c    Note: use [sql
1f590 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74  ite3_errmsg()] t
1f5a0 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a  o find the text.
1f5b0 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e  ** of the parsin
1f5c0 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73  g error that res
1f5d0 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49  ults in an [SQLI
1f5e0 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72  TE_SCHEMA] retur
1f5f0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
1f600 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61  * <li>.** When a
1f610 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1f620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f630 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1f640 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1f650 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1f660 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1f670 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68  rror codes].  Th
1f680 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1f690 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
1f6a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1f6b0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
1f6c0 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
1f6d0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
1f6e0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75   code.** and you
1f6f0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
1f700 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
1f710 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
1f720 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a  set()] in order.
1f730 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  ** to find the u
1f740 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
1f750 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
1f760 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
1f770 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
1f780 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
1f790 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
1f7a0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
1f7b0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1f7c0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
1f7d0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ol>.**.** INVARI
1f7e0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
1f7f0 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
1f800 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
1f810 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1f820 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f830 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1f840 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
1f850 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
1f860 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
1f870 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
1f880 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
1f890 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  TF-8..**.** {H13
1f8a0 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  012} The [sqlite
1f8b0 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a  3_prepare16(db,z
1f8c0 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
1f8d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f8e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1f8f0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1f900 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1f910 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1f920 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1f930 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1f940 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1f950 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1f960 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  er..**.** {H1301
1f970 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
1f980 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1f990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f9a0 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
1f9b0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1f9c0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1f9d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1f9e0 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74  ro, the SQL text
1f9f0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
1fa00 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69  read from zSql i
1fa10 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
1fa20 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1fa30 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inator..**.** {H
1fa40 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42  13014} If the nB
1fa50 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
1fa60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fa70 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
1fa80 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
1fa90 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
1faa0 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  ants is non-nega
1fab0 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f  tive, then at mo
1fac0 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20  st nBytes bytes 
1fad0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  of.**          S
1fae0 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20  QL text is read 
1faf0 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a  from zSql..**.**
1fb00 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71   {H13015} In [sq
1fb10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1fb20 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54  (db,zSql,N,P,pzT
1fb30 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61  ail)] and its va
1fb40 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20  riants.**       
1fb50 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69     if the zSql i
1fb60 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1fb70 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  ns more than one
1fb80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1fb90 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70  *          and p
1fba0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
1fbb0 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  L, then *pzTail 
1fbc0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1fbd0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
1fbe0 20 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70      first byte p
1fbf0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1fc00 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
1fc10 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a  tement in zSql..
1fc20 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1fc30 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54  o>What does *pzT
1fc40 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20  ail point to if 
1fc50 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61  there is one sta
1fc60 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a  tement?</todo>.*
1fc70 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20  *.** {H13016} A 
1fc80 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1fc90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1fca0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
1fcb0 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a  ,ppStmt,...)].**
1fcc0 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65            or one
1fcd0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
1fce0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70   writes into *pp
1fcf0 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74  Stmt a pointer t
1fd00 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1fd10 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
1fd20 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f  atement] or a po
1fd30 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66  inter to NULL if
1fd40 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a   zSql contains.*
1fd50 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69  *          nothi
1fd60 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68  ng other than wh
1fd70 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d  itespace or comm
1fd80 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ents..**.** {H13
1fd90 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  019} The [sqlite
1fda0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fdb0 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74  interface and it
1fdc0 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72  s variants retur
1fdd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
1fde0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20  QLITE_OK] or an 
1fdf0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
1fe00 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61  or code] upon fa
1fe10 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ilure..**.** {H1
1fe20 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71  3021} Before [sq
1fe30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1fe40 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74  ,zSql,nByte,ppSt
1fe50 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69  mt,pzTail)] or i
1fe60 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  ts.**          v
1fe70 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20  ariants returns 
1fe80 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61  an error (any va
1fe90 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1fea0 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20  SQLITE_OK]),.** 
1feb0 20 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69           they fi
1fec0 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20  rst set *ppStmt 
1fed0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
1fee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1fef0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1ff00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1ff10 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1ff20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1ff30 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1ff40 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1ff50 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1ff60 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1ff70 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1ff80 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1ff90 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1ffa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1ffb0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1ffc0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1ffd0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ffe0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1fff0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
20000 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
20010 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
20020 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
20030 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
20040 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
20050 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
20060 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
20070 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
20080 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
20090 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
200a0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
200b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
200c0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
200d0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
200e0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
200f0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
20100 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
20110 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
20120 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
20130 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
20140 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
20150 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
20160 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
20170 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
20180 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
20190 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
201a0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
201b0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
201c0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
201d0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
201e0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
201f0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
20200 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
20210 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
20220 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
20230 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
20240 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
20250 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
20260 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
20270 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
20280 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
20290 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
202a0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
202b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
202c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
202d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
202e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
202f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
20300 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
20310 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
20320 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
20330 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
20340 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
20350 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
20360 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
20370 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
20380 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
20390 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
203a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
203b0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
203c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
203d0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
203e0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
203f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52  .);../*.** CAPIR
20400 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
20410 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31  tatement SQL {H1
20420 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a  3100} <H13000>.*
20430 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
20440 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
20450 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
20460 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
20470 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
20480 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
20490 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
204a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
204b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
204c0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
204d0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
204e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
204f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
20500 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
20510 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
20520 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49  **.** {H13101} I
20530 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
20540 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
20550 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e  d as the argumen
20560 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
20570 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
20580 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
20590 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
205a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
205b0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
205c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
205d0 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20  e16_v2()], then 
205e0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
205f0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
20600 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f      a pointer to
20610 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
20620 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ed string contai
20630 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e  ning a UTF-8 ren
20640 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  dering.**       
20650 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e     of the origin
20660 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  al SQL statement
20670 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d  ..**.** {H13102}
20680 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
20690 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
206a0 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  sed as the argum
206b0 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
206c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28     [sqlite3_sql(
206d0 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  )] was compiled 
206e0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
206f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
20700 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
20710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20720 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c  16()], then [sql
20730 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75  ite3_sql()] retu
20740 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
20750 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  er..**.** {H1310
20760 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65  3} The string re
20770 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
20780 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61  e3_sql(S)] is va
20790 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a  lid until the.**
207a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
207b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
207c0 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e   is deleted usin
207d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
207e0 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ize(S)]..*/.cons
207f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20800 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
20810 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
20820 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
20830 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
20840 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30  ue Object {H1500
20850 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
20860 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
20870 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20880 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
20890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
208a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
208b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
208c0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
208d0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
208e0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
208f0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
20900 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
20910 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
20920 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
20930 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
20940 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72  res. Values stor
20950 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
20960 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
20970 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
20980 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
20990 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
209a0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
209b0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
209c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
209d0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
209e0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
209f0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
20a00 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
20a10 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
20a20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
20a30 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
20a40 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
20a50 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
20a60 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
20a70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20a80 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
20a90 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
20aa0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
20ab0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
20ac0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
20ad0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
20ae0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
20af0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
20b00 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
20b10 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
20b20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
20b30 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
20b40 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
20b50 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
20b60 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
20b70 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
20b80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
20b90 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
20ba0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
20bb0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
20bc0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
20bd0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
20be0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
20bf0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
20c00 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
20c10 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
20c20 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
20c30 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
20c40 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
20c50 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
20c60 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
20c70 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
20c80 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
20c90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
20ca0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
20cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
20cc0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
20cd0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
20ce0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
20cf0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
20d00 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
20d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20d20 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
20d30 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
20d40 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
20d50 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
20d60 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
20d70 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
20d80 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
20d90 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
20da0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
20db0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
20dc0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
20dd0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
20de0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20df0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
20e00 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
20e10 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
20e20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
20e30 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
20e40 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
20e50 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
20e60 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
20e70 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
20e80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20e90 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
20ea0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68  protected..** Th
20eb0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
20ec0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
20ed0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
20ee0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
20ef0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
20f00 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
20f10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20f20 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
20f30 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
20f40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
20f50 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
20f60 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
20f70 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
20f80 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
20f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
20fa0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
20fb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
20fc0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
20fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20fe0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
20ff0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
21000 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
21010 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
21020 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
21030 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d   Object {H16001}
21040 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
21050 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
21060 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
21070 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
21080 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
21090 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
210a0 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e   object.  A poin
210b0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
210c0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
210d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
210e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
210f0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
21100 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
21110 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
21120 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
21130 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
21140 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
21150 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
21160 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
21170 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
21180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
21190 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
211a0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
211b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
211c0 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
211d0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
211e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
211f0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
21200 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
21210 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
21220 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
21230 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
21240 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
21250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
21260 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
21270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21280 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
21290 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
212a0 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20  ements {H13500} 
212b0 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S70300>.** KEYW
212c0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
212d0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
212e0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
212f0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
21300 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
21310 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
21320 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
21330 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
21340 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51  .**.** In the SQ
21350 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20  L strings input 
21360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
21370 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
21380 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
21390 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
213a0 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61 72  eplaced by a par
213b0 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66  ameter in one of
213c0 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a   these forms:.**
213d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
213e0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
213f0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
21400 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
21410 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
21420 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
21430 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d  e parameter form
21440 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e  s shown above NN
21450 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  N is an integer 
21460 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
21470 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d  VVV is an alpha-
21480 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65  numeric paramete
21490 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75  r name. The valu
214a0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
214b0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
214c0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
214d0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
214e0 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
214f0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
21500 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
21510 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
21520 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
21530 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
21540 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
21550 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
21560 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
21570 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
21580 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
21590 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
215a0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
215b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
215c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
215d0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
215e0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
215f0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
21600 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
21610 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
21620 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  .** The leftmost
21630 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
21640 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
21650 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65  .  When the same
21660 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
21670 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
21680 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
21690 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
216a0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
216b0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
216c0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
216d0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
216e0 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66  ..** The index f
216f0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
21700 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
21710 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
21720 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21730 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21740 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
21750 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
21760 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
21770 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
21780 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
21790 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
217a0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
217b0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
217c0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
217d0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
217e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
217f0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
21800 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
21810 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
21820 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
21830 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
21840 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
21850 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e   In those routin
21860 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
21870 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
21880 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
21890 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
218a0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
218b0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
218c0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
218d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
218e0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
218f0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
21900 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
21910 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66  haracters..** If
21920 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21930 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
21940 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
21950 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
21960 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
21970 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
21980 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
21990 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
219a0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
219b0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
219c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
219d0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
219e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
219f0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
21a00 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
21a10 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
21a20 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
21a30 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
21a40 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
21a50 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66  h it. If the fif
21a60 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
21a70 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
21a80 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
21a90 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
21aa0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
21ab0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
21ac0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
21ad0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
21ae0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
21af0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
21b00 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
21b10 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
21b20 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
21b30 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
21b40 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
21b50 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
21b60 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
21b70 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
21b80 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
21b90 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
21ba0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
21bb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
21bc0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
21bd0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
21be0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
21bf0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
21c00 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41   with zeroes.  A
21c10 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
21c20 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
21c30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
21c40 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
21c50 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
21c60 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
21c70 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
21c80 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
21c90 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
21ca0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
21cb0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
21cc0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
21cd0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
21ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
21cf0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
21d00 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
21d10 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67  utines..** A neg
21d20 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
21d30 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
21d40 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
21d50 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
21d60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
21d70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
21d80 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61  must be called a
21d90 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fter.** [sqlite3
21da0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28  _prepare_v2()] (
21db0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
21dc0 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ) or [sqlite3_re
21dd0 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65  set()] and.** be
21de0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
21df0 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e  ep()]..** Bindin
21e00 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
21e10 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
21e20 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
21e30 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20  ine..** Unbound 
21e40 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
21e50 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
21e60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  LL..**.** These 
21e70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21e80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
21e90 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72  uccess or an err
21ea0 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e  or code if.** an
21eb0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
21ec0 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47  g.  [SQLITE_RANG
21ed0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
21ee0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
21ef0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
21f00 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49  of range.  [SQLI
21f10 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
21f20 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
21f30 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c  ) fails..** [SQL
21f40 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68  ITE_MISUSE] migh
21f50 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
21f60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
21f70 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a  are called on a.
21f80 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  ** virtual machi
21f90 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77  ne that is the w
21fa0 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68  rong state or wh
21fb0 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20  ich has already 
21fc0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  been finalized..
21fd0 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20  ** Detection of 
21fe0 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69  misuse is unreli
21ff0 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69  able.  Applicati
22000 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64  ons should not d
22010 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49  epend.** on SQLI
22020 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e  TE_MISUSE return
22030 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  s.  SQLITE_MISUS
22040 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  E is intended to
22050 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61   indicate a.** a
22060 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
22070 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
22080 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22090 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
220a0 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65  t.** panic rathe
220b0 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51  r than return SQ
220c0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a  LITE_MISUSE..**.
220d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
220e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
220f0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
22100 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22110 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
22120 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
22130 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22140 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22150 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22160 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53   {H13506} The [S
22170 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
22180 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65  piler] recognize
22190 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20  s tokens of the 
221a0 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20  forms.**        
221b0 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22    "?", "?NNN", "
221c0 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61  $VVV", ":VVV", a
221d0 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 51 4c  nd "@VVV" as SQL
221e0 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20   parameters,.** 
221f0 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4e           where N
22200 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e  NN is any sequen
22210 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ce of one or mor
22220 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20  e digits.**     
22230 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 20 56       and where V
22240 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e  VV is any sequen
22250 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ce of one or mor
22260 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a  e alphanumeric.*
22270 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 72 61  *          chara
22280 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70  cters or "::" op
22290 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
222a0 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f  d by a string co
222b0 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  ntaining.**     
222c0 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61       no spaces a
222d0 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  nd contained wit
222e0 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e  hin parentheses.
222f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20  .**.** {H13509} 
22300 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75  The initial valu
22310 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  e of an SQL para
22320 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  meter is NULL..*
22330 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68  *.** {H13512} Th
22340 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
22350 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
22360 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68  is one larger th
22370 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  an the.**       
22380 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78     largest index
22390 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
223a0 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f  r to the left, o
223b0 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  r 1 if.**       
223c0 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68     the "?" is th
223d0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
223e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
223f0 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64  {H13515} The ind
22400 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20  ex of an "?NNN" 
22410 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
22420 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e   the integer NNN
22430 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d  ..**.** {H13518}
22440 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
22450 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c   ":VVV", "$VVV",
22460 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70   or "@VVV" SQL p
22470 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
22480 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
22490 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   as the index of
224a0 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72   leftmost occurr
224b0 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d  ences of the sam
224c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
224d0 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20  rameter, or one 
224e0 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61  more than the la
224f0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72  rgest index over
22500 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
22510 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
22520 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20  he left if this 
22530 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  is the first occ
22540 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20  urrence.**      
22550 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61      of this para
22560 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74  meter, or 1 if t
22570 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d  his is the leftm
22580 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ost parameter..*
22590 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68  *.** {H13521} Th
225a0 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  e [SQL statement
225b0 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73   compiler] fails
225c0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
225d0 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20  _RANGE].**      
225e0 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 68 65      error if the
225f0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
22600 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
22610 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20  ss than 1.**    
22620 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 65 72        or greater
22630 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c   than the compil
22640 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41  e-time SQLITE_MA
22650 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
22660 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  R.**          pa
22670 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
22680 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f  H13524} Calls to
22690 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
226a0 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
226b0 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a  nd(S,N,V,...)].*
226c0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63  *          assoc
226d0 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56  iate the value V
226e0 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61   with all SQL pa
226f0 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20  rameters having 
22700 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  an.**          i
22710 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65  ndex of N in the
22720 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22730 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
22740 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f  H13527} Calls to
22750 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22760 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
22770 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  nd(S,N,...)].** 
22780 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64           overrid
22790 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  e prior calls wi
227a0 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
227b0 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a  es of S and N..*
227c0 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69  *.** {H13530} Bi
227d0 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68  ndings establish
227e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
227f0 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74  ind_text | sqlit
22800 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a  e3_bind(S,...)].
22810 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73  **          pers
22820 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73  ist across calls
22830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
22840 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  et(S)]..**.** {H
22850 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20  13533} In calls 
22860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22870 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
22880 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
22890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
228a0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
228b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
228c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
228d0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53  16(S,N,V,L,D)] S
228e0 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20  QLite binds the 
228f0 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20  first L.**      
22900 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65      bytes of the
22910 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
22920 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c  pointed to by V,
22930 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20   when L.**      
22940 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74      is non-negat
22950 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
22960 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  36} In calls to 
22970 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22980 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f  xt(S,N,V,L,D)] o
22990 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
229a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
229b0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53  16(S,N,V,L,D)] S
229c0 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72  QLite binds char
229d0 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  acters.**       
229e0 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67     from V throug
229f0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
22a00 20 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20   character when 
22a10 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  L is negative..*
22a20 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e  *.** {H13539} In
22a30 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22a40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
22a50 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
22a60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
22a70 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
22a80 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
22a90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22aa0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
22ab0 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
22ac0 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20  the special.**  
22ad0 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74          constant
22ae0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
22af0 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
22b00 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20   that the value 
22b10 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  V.**          is
22b20 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20   held in static 
22b30 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
22b40 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68  that will not ch
22b50 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
22b60 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
22b70 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64  time of the bind
22b80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ing..**.** {H135
22b90 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  42} In calls to 
22ba0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22bb0 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
22bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
22bd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
22be0 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
22bf0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22c00 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
22c10 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
22c20 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61   D is the specia
22c30 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  l.**          co
22c40 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54  nstant [SQLITE_T
22c50 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72  RANSIENT], the r
22c60 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a  outine makes a.*
22c70 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61  *          priva
22c80 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76  te copy of the v
22c90 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69 74  alue V before it
22ca0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
22cb0 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c  {H13545} In call
22cc0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22cd0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
22ce0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
22cf0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22d00 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
22d10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
22d20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22d30 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
22d40 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69   when D is a poi
22d50 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  nter to.**      
22d60 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20      a function, 
22d70 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
22d80 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  hat function to 
22d90 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20  destroy the.**  
22da0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20          value V 
22db0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
22dc0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
22dd0 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
22de0 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73  H13548} In calls
22df0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22e00 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56  d_zeroblob(S,N,V
22e10 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62  ,L)] the value b
22e20 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ound.**         
22e30 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20   is a BLOB of L 
22e40 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f  bytes, or a zero
22e50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20  -length BLOB if 
22e60 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  L is negative..*
22e70 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e  *.** {H13551} In
22e80 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22e90 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c  e3_bind_value(S,
22ea0 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75  N,V)] the V argu
22eb0 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20  ment may.**     
22ec0 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61       be either a
22ed0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
22ee0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
22ef0 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20  t or an.**      
22f00 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64      [unprotected
22f10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
22f20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
22f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22f40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22f50 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
22f60 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
22f70 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
22f80 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
22f90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22fa0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
22fb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22fc0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
22fd0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
22fe0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
22ff0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
23000 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
23010 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
23020 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
23030 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23040 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
23050 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
23060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
23070 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
23080 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
23090 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
230a0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
230b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
230c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
230d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
230e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
230f0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
23100 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
23110 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
23120 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
23130 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
23140 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23150 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
23160 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
23170 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
23180 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37  ers {H13600} <S7
23190 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
231a0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
231b0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
231c0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
231d0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
231e0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
231f0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
23200 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
23210 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
23220 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
23230 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
23240 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
23250 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
23260 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
23270 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
23280 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
23290 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
232a0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
232b0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
232c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
232d0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
232e0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
232f0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
23300 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
23310 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
23320 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
23330 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
23340 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
23350 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
23360 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
23370 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
23380 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64  he ?NNN are used
23390 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
233a0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
233b0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  st..**.** See al
233c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
233d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
233e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
233f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23400 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
23410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
23420 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
23430 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
23440 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
23450 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3601} The [sqlit
23460 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23470 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  r_count(S)] inte
23480 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
23490 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61            the la
234a0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61  rgest index of a
234b0 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
234c0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
234d0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
234e0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
234f0 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20  0 if S contains 
23500 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  no SQL parameter
23510 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
23520 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23530 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
23540 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
23550 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
23560 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
23570 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30   {H13620} <S7030
23580 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
23590 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
235a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
235b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a  ame of the n-th.
235c0 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  ** [SQL paramete
235d0 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  r] in a [prepare
235e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
235f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
23600 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
23610 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
23620 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
23630 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
23640 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
23650 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
23660 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
23670 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
23680 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
23690 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
236a0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
236b0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
236c0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
236d0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
236e0 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
236f0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
23700 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
23710 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
23720 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
23730 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66  and are also ref
23740 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f  erred to as "ano
23750 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
23760 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  s"..**.** The fi
23770 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
23780 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
23790 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
237a0 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  ** If the value 
237b0 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  n is out of rang
237c0 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68  e or if the n-th
237d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
237e0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
237f0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
23800 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
23810 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
23820 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
23830 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
23840 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
23850 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
23860 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
23870 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
23880 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
23890 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
238a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
238b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
238c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
238d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
238e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
238f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23900 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
23910 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
23920 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
23930 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
23940 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
23950 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
23960 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23970 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
23980 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
23990 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38           a UTF-8
239a0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
239b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
239c0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a  L parameter in.*
239d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
239e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
239f0 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64  nt] S having ind
23a00 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ex N, or.**     
23a10 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65       NULL if the
23a20 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72  re is no SQL par
23a30 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
23a40 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  x N or if the.**
23a50 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
23a60 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
23a70 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73   is an anonymous
23a80 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a   parameter "?"..
23a90 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
23aa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23ab0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
23ac0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
23ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23ae0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
23af0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
23b00 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d  en Name {H13640}
23b10 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
23b20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
23b30 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
23b40 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
23b50 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64  ame.  The.** ind
23b60 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
23b70 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
23b80 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
23b90 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
23ba0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
23bb0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
23bc0 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a  ind()].  A zero.
23bd0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
23be0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
23bf0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
23c00 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72  .  The parameter
23c10 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
23c20 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
23c30 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
23c40 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
23c50 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
23c60 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
23c70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
23c80 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
23c90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23ca0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23cb0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
23cc0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
23cd0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
23ce0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
23cf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23d00 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
23d10 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
23d20 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34  TS:.**.** {H1364
23d30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
23d40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
23d50 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ndex(S,N)] inter
23d60 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
23d70 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64           the ind
23d80 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
23d90 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70  ter in the [prep
23da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
23db0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68  **          S wh
23dc0 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73  ose name matches
23dd0 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e   the UTF-8 strin
23de0 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65  g N, or 0 if the
23df0 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  re is.**        
23e00 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69    no match..*/.i
23e10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
23e20 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
23e30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
23e40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
23e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e60 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
23e70 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
23e80 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b  ared Statement {
23e90 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e  H13660} <S70300>
23ea0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
23eb0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
23ec0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
23ed0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
23ee0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
23ef0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
23f00 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
23f10 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
23f20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55  statement]..** U
23f30 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
23f40 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
23f50 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
23f60 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  NULL..**.** INVA
23f70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23f80 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  13661} The [sqli
23f90 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
23fa0 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  gs(S)] interface
23fb0 20 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a   resets all SQL.
23fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
23fd0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69  meter bindings i
23fe0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
23ff0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63  statement] S bac
24000 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  k to NULL..*/.in
24010 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
24020 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
24030 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
24040 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
24050 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
24060 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33   Result Set {H13
24070 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  710} <S10700>.**
24080 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
24090 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
240a0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
240b0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
240c0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
240d0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73  statement]. This
240e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
240f0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
24100 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
24110 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
24120 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
24130 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
24140 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e  DATE])..**.** IN
24150 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
24160 7b 48 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71  {H13711} The [sq
24170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
24180 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
24190 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
241a0 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
241b0 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68     columns in th
241c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e  e result set gen
241d0 65 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70  erated by the [p
241e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
241f0 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
24200 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73    or 0 if S does
24210 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20   not generate a 
24220 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
24230 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
24240 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
24250 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
24260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
24270 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
24280 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33   Result Set {H13
24290 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  720} <S10700>.**
242a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
242b0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
242c0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
242d0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
242e0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
242f0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
24300 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
24310 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f    The sqlite3_co
24320 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
24330 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24340 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24350 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24360 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
24370 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
24380 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
24390 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
243a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
243b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
243c0 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20  ing.  The first 
243d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
243e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
243f0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
24400 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
24410 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
24420 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
24430 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
24440 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
24450 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
24460 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
24470 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
24480 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
24490 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
244a0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
244b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
244c0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
244d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
244e0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
244f0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
24500 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
24510 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
24520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24530 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
24540 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
24550 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
24560 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
24570 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
24580 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
24590 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
245a0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
245b0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
245c0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
245d0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
245e0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
245f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
24600 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
24610 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
24620 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
24630 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
24640 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
24650 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
24660 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
24670 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
24680 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
24690 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
246a0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
246b0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
246c0 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
246d0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
246e0 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  xt..**.** INVARI
246f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
24700 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  721} A successfu
24710 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
24720 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
24730 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a  umn_name(S,N)].*
24740 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
24750 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24760 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68   name of the Nth
24770 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
24780 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
24790 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  the leftmost col
247a0 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73  umn) for the res
247b0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a  ult set of the.*
247c0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
247d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
247e0 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  S as a zero-term
247f0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
24800 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ing..**.** {H137
24810 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  23} A successful
24820 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
24830 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24840 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a  mn_name16(S,N)].
24850 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
24860 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24870 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74  e name of the Nt
24880 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20  h column (where 
24890 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  0 is.**         
248a0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   the leftmost co
248b0 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65  lumn) for the re
248c0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a  sult set of the.
248d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
248e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
248f0 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72   S as a zero-ter
24900 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73  minated UTF-16 s
24910 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
24920 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
24930 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
24940 2a 20 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b  * {H13724} The [
24950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24960 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ame()] and [sqli
24970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
24980 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
24990 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
249a0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
249b0 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e  r if they are un
249c0 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20  able to.**      
249d0 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d      allocate mem
249e0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69  ory to hold thei
249f0 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20  r normal return 
24a00 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  strings..**.** {
24a10 48 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e  H13725} If the N
24a20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
24a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24a40 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  me(S,N)] or.**  
24a50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24a60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
24a70 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72  ,N)] is out of r
24a80 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ange, then the.*
24a90 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
24aa0 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
24ab0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
24ac0 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20  ** {H13726} The 
24ad0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
24ae0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
24af0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61  umn_name(S,N)] a
24b00 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
24b10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24b20 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20  ame16(S,N)] are 
24b30 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
24b40 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  next.**         
24b50 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
24b60 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65  routine with the
24b70 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61   same S and N pa
24b80 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
24b90 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73       or until [s
24ba0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24bb0 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
24bc0 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68  *.** {H13727} Wh
24bd0 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  en a result colu
24be0 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  mn of a [SELECT]
24bf0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61   statement conta
24c00 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
24c10 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68  an AS clause, th
24c20 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63  e name of that c
24c30 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65  olumn is the ide
24c40 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20  ntifier.**      
24c50 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74      to the right
24c60 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f   of the AS keywo
24c70 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  rd..*/.const cha
24c80 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
24c90 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
24ca0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
24cb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
24cc0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
24cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24ce0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
24cf0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
24d00 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
24d10 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30  y Result {H13740
24d20 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
24d30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24d40 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
24d50 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61  to determine wha
24d60 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74  t column of what
24d70 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69  .** table in whi
24d80 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65  ch database a re
24d90 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43  sult of a [SELEC
24da0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  T] statement com
24db0 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20  es from..** The 
24dc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24dd0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
24de0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
24df0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
24e00 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
24e10 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
24e20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
24e30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
24e40 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
24e50 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
24e60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
24e70 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
24e80 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
24e90 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
24ea0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
24eb0 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ame..** The retu
24ec0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
24ed0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
24ee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24ef0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
24f00 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
24f10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
24f20 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
24f30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
24f40 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
24f50 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
24f60 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
24f70 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75  * The names retu
24f80 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
24f90 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
24fa0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
24fb0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
24fc0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
24fd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
24fe0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f  gument to the fo
24ff0 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73  llowing calls is
25000 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25010 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
25020 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
25030 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
25040 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
25050 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
25060 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
25070 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
25080 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
25090 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
250a0 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
250b0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
250c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
250d0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
250e0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
250f0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
25100 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
25110 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
25120 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
25130 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  LL.  These routi
25140 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
25150 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
25160 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
25170 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
25180 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68  .  Otherwise, th
25190 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
251a0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
251b0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
251c0 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e  le.** and column
251d0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
251e0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
251f0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
25200 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20  .** As with all 
25210 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
25220 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78  s, those postfix
25230 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  ed with "16" ret
25240 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
25250 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74  coded strings, t
25260 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
25270 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
25280 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
25290 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
252a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
252b0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
252c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
252d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
252e0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
252f0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
25300 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
25310 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d  ..**.** {A13751}
25320 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
25330 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
25340 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
25350 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
25360 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
25370 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
25380 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
25390 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
253a0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
253b0 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
253c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
253d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
253e0 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  741} The [sqlite
253f0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
25400 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
25410 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
25420 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25430 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
25440 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
25450 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
25460 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
25470 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
25480 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
25490 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
254a0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
254b0 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
254c0 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
254d0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
254e0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
254f0 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
25500 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
25510 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
25520 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
25530 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25540 2a 20 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b  * {H13742} The [
25550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25560 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53  atabase_name16(S
25570 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25580 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
25590 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
255a0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
255b0 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
255c0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
255d0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20  he database.**  
255e0 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69          from whi
255f0 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
25600 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
25610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25620 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20  ent] S is.**    
25630 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c        extracted,
25640 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
25650 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
25660 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
25670 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
25680 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
25690 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
256a0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
256b0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
256c0 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3743} The [sqlit
256d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
256e0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
256f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
25700 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25710 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
25720 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
25730 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d  f the table from
25740 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
25750 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
25760 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
25770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25780 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
25790 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
257a0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
257b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
257c0 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
257d0 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
257e0 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
257f0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
25800 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
25810 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
25820 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3744} The [sqlit
25830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
25840 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
25850 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
25860 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25870 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
25880 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
25890 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
258a0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
258b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
258c0 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20  m which the Nth 
258d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
258e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
258f0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a  tatement] S is.*
25900 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61  *          extra
25910 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
25920 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
25930 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
25940 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
25950 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
25960 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
25970 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
25980 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25990 2a 20 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b  * {H13745} The [
259a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
259b0 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  rigin_name(S,N)]
259c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
259d0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
259e0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
259f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
25a00 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
25a10 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
25a20 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
25a30 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
25a40 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
25a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25a60 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
25a70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
25a80 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
25a90 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
25aa0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
25ab0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
25ac0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
25ad0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
25ae0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
25af0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
25b00 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
25b10 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
25b20 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
25b30 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
25b40 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25b50 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
25b60 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
25b70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
25b80 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
25b90 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
25ba0 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
25bb0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
25bc0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  mn of the.**    
25bd0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25be0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
25bf0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
25c00 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
25c10 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
25c20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
25c30 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
25c40 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
25c50 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
25c60 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
25c70 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
25c80 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20  ** {H13748} The 
25c90 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72  return values fr
25ca0 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  om.**          [
25cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25cc0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
25cd0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
25ce0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
25cf0 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64         are valid
25d00 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d   for the lifetim
25d10 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  e of the [prepar
25d20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
25d30 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
25d40 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  il the encoding 
25d50 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e  is changed by an
25d60 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a  other metadata.*
25d70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
25d80 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68  face call for th
25d90 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20  e same prepared 
25da0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
25db0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  lumn..**.** ASSU
25dc0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
25dd0 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f  A13751} If two o
25de0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
25df0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
25e00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
25e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
25e20 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
25e30 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
25e40 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
25e50 20 20 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65      for the same
25e60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25e70 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
25e80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
25e90 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20      at the same 
25ea0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
25eb0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
25ec0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
25ed0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25ee0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25ef0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25f00 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
25f10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25f20 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
25f30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
25f40 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
25f50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25f60 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
25f70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25f80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25f90 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
25fa0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25fb0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
25fc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
25fd0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
25fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25ff0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
26000 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26010 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
26020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26040 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
26050 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
26060 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20  Result {H13760} 
26070 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
26080 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
26090 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
260a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
260b0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
260c0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
260d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
260e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
260f0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
26100 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
26110 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
26120 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
26130 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
26140 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
26150 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
26160 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
26170 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
26180 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66  is returned.  If
26190 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
261a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
261b0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
261c0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
261d0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
261e0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
261f0 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  ed..** The retur
26200 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
26210 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
26220 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ed. {END}.**.** 
26230 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
26240 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26250 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
26260 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
26270 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
26280 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
26290 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
262a0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
262b0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
262c0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
262d0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
262e0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
262f0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
26300 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
26310 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
26320 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
26330 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
26340 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
26350 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
26360 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
26370 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
26380 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
26390 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
263a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
263b0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
263c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
263d0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
263e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
263f0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
26400 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
26410 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
26420 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
26430 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
26440 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
26450 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
26460 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
26470 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
26480 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
26490 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
264a0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
264b0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
264c0 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  e values..**.** 
264d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
264e0 2a 20 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75  * {H13761}  A su
264f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
26500 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26510 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
26520 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
26530 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
26540 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
26550 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
26560 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
26570 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  type.**         
26580 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63    of the table c
26590 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61  olumn that appea
265a0 72 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f  rs as the Nth co
265b0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a  lumn (numbered.*
265c0 2a 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  *           from
265d0 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c   0) of the resul
265e0 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72  t set to the [pr
265f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26600 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ] S..**.** {H137
26610 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  62}  A successfu
26620 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
26630 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
26640 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  pe16(S,N)].**   
26650 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
26660 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26670 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
26680 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
26690 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  g.**           c
266a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
266b0 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20  clared datatype 
266c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
266d0 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  umn that appears
266e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
266f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26700 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30  (numbered from 0
26710 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  ) of the result 
26720 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  set to the.**   
26730 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
26740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
26750 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20  **.** {H13763}  
26760 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
26770 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61  n 0 or N is grea
26780 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ter than or equa
26790 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
267a0 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20    the number of 
267b0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b  columns in the [
267c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
267d0 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20  nt] S,.**       
267e0 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74      or if the Nt
267f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
26800 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
26810 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65  r subquery rathe
26820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
26830 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75  han a table colu
26840 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  mn, or if a memo
26850 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
26860 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  ilure.**        
26870 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
26880 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72   encoding conver
26890 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20  sions, then.**  
268a0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74           calls t
268b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
268c0 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d  n_decltype(S,N)]
268d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
268e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
268f0 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29  _decltype16(S,N)
26900 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a  ] return NULL..*
26910 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
26920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
26930 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
26940 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
26950 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
26960 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
26970 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26980 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26990 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
269a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
269b0 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e  H13200} <S10000>
269c0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
269d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
269e0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
269f0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
26a00 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
26a10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
26a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26a30 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
26a40 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
26a50 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
26a60 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
26a70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
26a80 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
26a90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
26aa0 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
26ab0 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
26ac0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
26ad0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
26ae0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
26af0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
26b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
26b10 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
26b20 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
26b30 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
26b40 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
26b50 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
26b60 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
26b70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26b80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
26b90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
26ba0 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
26bb0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
26bc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26bd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26be0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
26bf0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
26c00 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
26c10 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
26c20 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
26c30 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
26c40 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
26c50 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
26c60 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
26c70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
26c80 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
26c90 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
26ca0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
26cb0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
26cc0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
26cd0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
26ce0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
26cf0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
26d00 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
26d10 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
26d20 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
26d30 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
26d40 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
26d50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
26d60 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
26d70 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
26d80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d   [SQLITE_BUSY] m
26d90 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
26da0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
26db0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
26dc0 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
26dd0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
26de0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
26df0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
26e00 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
26e10 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
26e20 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
26e30 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
26e40 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
26e50 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
26e60 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
26e70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
26e80 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
26e90 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
26ea0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
26eb0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
26ec0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
26ed0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
26ee0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
26ef0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
26f00 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
26f10 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
26f20 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
26f30 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
26f40 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
26f50 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
26f60 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
26f70 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
26f80 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
26f90 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
26fa0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
26fb0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
26fc0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
26fd0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
26fe0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
26ff0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
27000 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27010 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
27020 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
27030 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
27040 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
27050 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
27060 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
27070 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
27080 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
27090 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
270a0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
270b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
270c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
270d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
270e0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
270f0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
27100 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
27110 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
27120 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
27130 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
27140 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
27150 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
27160 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
27170 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
27180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
27190 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
271a0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
271b0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
271c0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
271d0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
271e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
271f0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
27200 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
27210 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
27220 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
27230 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
27240 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
27250 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
27260 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
27270 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
27280 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
27290 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
272a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
272b0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
272c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
272d0 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22  t].  In the "v2"
272e0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
272f0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
27300 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
27310 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
27320 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
27330 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
27340 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
27350 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
27360 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
27370 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
27380 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
27390 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
273a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
273b0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
273c0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
273d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
273e0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
273f0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
27400 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
27410 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
27420 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
27430 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
27440 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
27450 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
27460 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
27470 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
27480 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
27490 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
274a0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
274b0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
274c0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
274d0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
274e0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
274f0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
27500 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
27510 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
27520 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
27530 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
27540 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
27550 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
27560 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
27570 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
27580 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
27590 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
275a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
275b0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
275c0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
275d0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
275e0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
275f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
27600 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
27610 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
27620 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
27630 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
27640 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
27650 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
27660 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
27670 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
27680 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
27690 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
276a0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
276b0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
276c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
276d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
276e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
276f0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
27700 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
27710 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
27720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27730 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
27740 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
27750 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
27760 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
27770 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
27780 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
27790 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
277a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
277b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
277c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
277d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32  NTS:.**.** {H132
277e0 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65  02}  If the [pre
277f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27800 20 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62   S is ready to b
27810 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  e run, then.**  
27820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27830 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e  3_step(S)] advan
27840 63 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65  ces that prepare
27850 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69  d statement unti
27860 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  l.**           c
27870 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74  ompletion or unt
27880 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74  il it is ready t
27890 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72  o return another
278a0 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20   row of the.**  
278b0 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
278c0 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e  set, or until an
278d0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
278e0 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
278f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
27900 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
27910 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
27920 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61  {H15304}  When a
27930 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27940 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65  3_step(S)] cause
27950 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
27960 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
27970 20 20 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e          S to run
27980 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20   to completion, 
27990 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
279a0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  urns [SQLITE_DON
279b0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  E]..**.** {H1530
279c0 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  6}  When a call 
279d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
279e0 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75  (S)] stops becau
279f0 73 65 20 69 74 20 69 73 20 72 65 61 64 79 20 74  se it is ready t
27a00 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  o.**           r
27a10 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
27a20 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
27a30 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20  set, it returns 
27a40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a  [SQLITE_ROW]..**
27a50 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66  .** {H15308}  If
27a60 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
27a70 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63  te3_step(S)] enc
27a80 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20  ounters an.**   
27a90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
27aa0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
27ab0 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
27ac0 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20  -time error,.** 
27ad0 20 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74            it ret
27ae0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
27af0 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  ate error code t
27b00 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  hat is not one o
27b10 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  f.**           [
27b20 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c  SQLITE_OK], [SQL
27b30 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51  ITE_ROW], or [SQ
27b40 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
27b50 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61  * {H15310}  If a
27b60 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
27b70 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
27b80 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20  ] or a run-time 
27b90 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  error.**        
27ba0 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
27bb0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
27bc0 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20  te3_step(S)].** 
27bd0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
27be0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27bf0 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75  ent] S created u
27c00 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
27c10 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61    legacy interfa
27c20 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
27c30 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
27c40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
27c50 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
27c60 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
27c70 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27c80 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
27c90 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51  LITE_ERROR], [SQ
27ca0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b  LITE_BUSY], or [
27cb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
27cc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
27cd0 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
27ce0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27cf0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
27d00 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
27d10 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20  lt set {H13770} 
27d20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S10700>.**.** R
27d30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
27d40 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
27d50 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
27d60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27d70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
27d80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37  TS:.**.** {H1377
27d90 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c  1}  After a call
27da0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
27db0 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72  p(S)] that retur
27dc0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ns [SQLITE_ROW],
27dd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
27de0 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
27df0 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
27e00 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
27e10 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20  e same value.** 
27e20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
27e30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27e40 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74  _count(S)] funct
27e50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ion..**.** {H137
27e60 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69  72}  After [sqli
27e70 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
27e80 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61   returned any va
27e90 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
27ea0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
27eb0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f  ITE_ROW] or befo
27ec0 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
27ed0 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  (S)] has been ca
27ee0 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20  lled on the.**  
27ef0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
27f00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f  ed statement] fo
27f10 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  r the first time
27f20 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a   since it was.**
27f30 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
27f40 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
27f50 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69  epared] or [sqli
27f60 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65  te3_reset | rese
27f70 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t],.**          
27f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
27f90 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
27fa0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
27fb0 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
27fc0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
27fd0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27ff0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
28000 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36  Datatypes {H1026
28010 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31  5} <S10110><S101
28020 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20>.** KEYWORDS:
28030 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
28040 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72  ** {H10266} Ever
28050 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
28060 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
28070 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
28080 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
28090 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
280a0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
280b0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
280c0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
280d0 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
280e0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
280f0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
28100 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NULL.** </ul> {E
28110 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
28120 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
28130 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
28140 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
28150 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
28160 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
28170 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
28180 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
28190 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
281a0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
281b0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
281c0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
281d0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
281e0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
281f0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
28200 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
28210 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
28220 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
28230 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
28240 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
28250 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
28260 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
28270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
28280 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
28290 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
282a0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
282b0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
282c0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
282d0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
282e0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
282f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
28300 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
28310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
28320 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
28330 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d  A Query {H13800}
28340 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
28350 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
28360 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
28370 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28380 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
28390 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
283a0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
283b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
283c0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
283d0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
283e0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
283f0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
28400 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
28410 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
28420 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
28430 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
28440 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
28450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28460 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
28470 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
28480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
28490 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
284a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
284b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
284c0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
284d0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
284e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
284f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
28500 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
28510 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
28520 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
28530 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
28540 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
28550 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28560 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
28570 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
28580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
28590 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
285a0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
285b0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
285c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
285d0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
285e0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
285f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
28600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
28610 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
28620 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
28630 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
28640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28650 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
28660 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
28670 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
28680 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
28690 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
286a0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
286b0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
286c0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
286d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
286e0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
286f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28700 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
28710 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
28720 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
28730 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
28740 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
28750 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
28760 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
28770 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
28780 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
28790 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
287a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
287b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
287c0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
287d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
287e0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
287f0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
28800 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
28810 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
28820 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28830 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28840 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
28850 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
28860 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
28870 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
28880 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
28890 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
288a0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
288b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
288c0 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
288d0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
288e0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
288f0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
28900 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
28910 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
28920 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
28930 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
28940 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
28950 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28960 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
28970 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
28980 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
28990 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
289a0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
289b0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
289c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
289d0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
289e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
289f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28a00 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
28a10 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
28a20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
28a30 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
28a40 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
28a50 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
28a60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
28a70 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
28a80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
28a90 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
28aa0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
28ab0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
28ac0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
28ad0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28ae0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28af0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
28b00 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
28b10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28b20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
28b30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
28b40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
28b50 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
28b60 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
28b70 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
28b80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
28b90 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
28ba0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
28bb0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
28bc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28bd0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
28be0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
28bf0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
28c00 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
28c10 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
28c20 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
28c30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
28c40 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
28c50 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
28c60 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
28c70 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
28c80 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
28c90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
28ca0 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
28cb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
28cc0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
28cd0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
28ce0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
28cf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
28d00 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
28d10 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
28d20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
28d30 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
28d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28d50 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
28d60 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
28d70 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
28d80 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
28d90 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
28da0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
28db0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
28dc0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
28dd0 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
28de0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
28df0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
28e00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
28e10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
28e20 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
28e30 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
28e40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
28e50 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
28e60 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
28e70 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
28e80 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
28e90 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
28ea0 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
28eb0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
28ec0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
28ed0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
28ee0 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
28ef0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
28f00 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
28f10 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
28f20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28f30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
28f40 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
28f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28f60 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
28f70 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
28f80 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
28f90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28fa0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
28fb0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
28fc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28fd0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
28fe0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
28ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
29000 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
29010 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
29020 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
29030 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
29040 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
29050 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
29060 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
29070 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
29080 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
29090 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
290a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
290b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
290c0 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
290d0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
290e0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
290f0 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
29100 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
29110 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
29120 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
29130 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
29140 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
29150 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
29160 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
29170 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
29180 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
29190 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
291a0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
291b0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
291c0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
291d0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
291e0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
291f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
29200 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
29210 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
29220 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
29230 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
29240 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
29250 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
29260 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29270 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
29280 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
29290 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
292a0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
292b0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
292c0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
292d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
292e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
292f0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
29300 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
29310 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
29320 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29330 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
29340 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
29350 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
29360 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29370 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
29380 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
29390 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
293a0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
293b0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
293c0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
293d0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
293e0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
293f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29400 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
29410 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
29420 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
29430 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
29440 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
29450 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
29460 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
29470 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
29480 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
29490 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
294a0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
294b0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
294c0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
294d0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
294e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
294f0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
29500 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
29510 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
29520 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
29530 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
29540 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
29550 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
29560 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
29570 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
29580 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
29590 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
295a0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
295b0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
295c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
295d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
295e0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
295f0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
29600 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
29610 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
29620 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
29630 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
29640 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
29650 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
29660 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
29670 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
29680 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
29690 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
296a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
296b0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
296c0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
296d0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
296e0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
296f0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
29700 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
29710 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
29720 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
29730 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
29740 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
29750 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
29760 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
29770 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
29780 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
29790 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
297a0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
297b0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
297c0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
297d0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
297e0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
297f0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
29800 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
29810 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29820 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
29830 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
29840 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
29850 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
29860 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
29870 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
29880 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
29890 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
298a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
298b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
298c0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
298d0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
298e0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
298f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
29900 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
29910 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29920 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
29930 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
29940 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
29950 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
29960 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
29970 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29980 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29990 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
299a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
299b0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
299c0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
299d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
299e0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
299f0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
29a00 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
29a10 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
29a20 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29a30 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
29a40 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
29a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29a60 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
29a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29a80 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
29a90 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
29aa0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
29ab0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
29ac0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
29ad0 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
29ae0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
29af0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
29b00 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
29b10 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
29b20 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
29b30 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
29b40 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
29b50 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
29b60 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
29b70 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
29b80 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
29b90 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
29ba0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
29bb0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
29bc0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
29bd0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
29be0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
29bf0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
29c00 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
29c10 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
29c20 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
29c30 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
29c40 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
29c50 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
29c60 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
29c70 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
29c80 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
29c90 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
29ca0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
29cb0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
29cc0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
29cd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
29ce0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
29cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29d00 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
29d10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29d20 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
29d30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29d40 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
29d50 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
29d60 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
29d70 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
29d80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29d90 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
29da0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
29db0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
29dc0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
29dd0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
29de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29df0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
29e00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29e10 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
29e20 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
29e30 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
29e40 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
29e50 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
29e60 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
29e70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29e80 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
29e90 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
29ea0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
29eb0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
29ec0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
29ed0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
29ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
29ef0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
29f00 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
29f10 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
29f20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
29f30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
29f40 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
29f50 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
29f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29f70 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
29f80 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
29f90 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
29fa0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
29fb0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
29fc0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
29fd0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
29fe0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
29ff0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a000 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2a010 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2a020 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
2a030 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2a040 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2a050 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2a060 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2a070 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2a080 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2a090 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2a0a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a0b0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2a0c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2a0d0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2a0e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2a0f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
2a100 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2a110 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2a120 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2a130 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2a140 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2a150 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2a160 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2a170 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2a180 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2a190 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2a1a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2a1b0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2a1c0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2a1d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2a1e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2a1f0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2a200 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2a210 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
2a220 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2a230 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  13803} The [sqli
2a240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2a250 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a260 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a270 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a280 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a290 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a2a0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2a2b0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2a2c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a2d0 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ] S into a BLOB 
2a2e0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2a2f0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
2a300 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
2a310 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a  nverted value..*
2a320 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68  *.** {H13806} Th
2a330 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2a340 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e  n_bytes(S,N)] in
2a350 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a360 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a370 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a380 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
2a390 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2a3a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2a3b0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2a3c0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2a3d0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2a3e0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2a3f0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2a400 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2a410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a420 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
2a430 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2a440 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
2a450 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d  ..**.** {H13809}
2a460 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a470 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e  lumn_bytes16(S,N
2a480 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2a490 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2a4a0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2a4b0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2a4c0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2a4d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a4e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2a4f0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2a500 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2a510 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2a520 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2a530 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a540 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a550 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  S,N)]..**.** {H1
2a560 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3812} The [sqlit
2a570 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
2a580 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2a590 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2a5a0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2a5b0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2a5c0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2a5d0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
2a5e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2a5f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a600 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
2a610 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2a620 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2a630 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2a640 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2a650 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68  *.** {H13815} Th
2a660 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2a670 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
2a680 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2a690 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
2a6a0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
2a6b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2a6c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
2a6d0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a6e0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a6f0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2a700 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2a710 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2a720 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
2a730 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
2a740 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2a750 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d  ..**.** {H13818}
2a760 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a770 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d  lumn_int64(S,N)]
2a780 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2a790 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2a7a0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2a7b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2a7c0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2a7d0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2a7e0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2a7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2a800 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2a810 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2a820 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2a830 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2a840 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2a850 2a 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b  * {H13821} The [
2a860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a870 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ext(S,N)] interf
2a880 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2a890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2a8a0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2a8b0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2a8c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2a8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2a8e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a8f0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a  ment] S into a z
2a900 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2a910 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20  TF-8.**         
2a920 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2a930 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a940 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2a950 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65  .** {H13824} The
2a960 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a970 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e  _text16(S,N)] in
2a980 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2a990 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a9a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2a9b0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2a9c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2a9d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2a9e0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2a9f0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2aa00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2aa10 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2aa20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2aa30 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2aa40 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e   order string an
2aa50 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  d returns.**    
2aa60 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
2aa70 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2aa80 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54  **.** {H13827} T
2aa90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2aaa0 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e  mn_type(S,N)] in
2aab0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2aac0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2aad0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2aae0 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2aaf0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2ab00 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2ab10 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2ab20 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2ab30 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2ab40 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2ab50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e  he Nth column in
2ab60 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2ab70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2ab80 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2ab90 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2aba0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2abb0 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68  *.** {H13830} Th
2abc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2abd0 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e  n_value(S,N)] in
2abe0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2abf0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
2ac00 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70  inter to an [unp
2ac10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ac20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2ac30 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2ac40 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2ac50 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2ac60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2ac70 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2ac80 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2ac90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2aca0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
2acb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2acc0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2acd0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2ace0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2acf0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
2ad00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2ad10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2ad20 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
2ad30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2ad40 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
2ad50 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
2ad60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ad70 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2ad80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2ad90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2ada0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2adb0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
2adc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
2add0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ade0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
2adf0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2ae00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ae10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2ae20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2ae30 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ae40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
2ae50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ae60 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2ae70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ae80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ae90 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
2aea0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
2aeb0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
2aec0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2aed0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
2aee0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
2aef0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2af00 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
2af10 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53  3300} <S70300><S
2af20 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
2af30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2af40 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2af50 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2af60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2af70 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2af80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2af90 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
2afa0 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78  sfully or not ex
2afb0 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
2afc0 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  hen.** SQLITE_OK
2afd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66   is returned. If
2afe0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
2aff0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
2b000 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65  ed then an.** [e
2b010 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
2b020 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2b030 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2b040 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b050 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2b060 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2b070 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
2b080 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
2b090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b0a0 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74  t].  If the virt
2b0b0 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
2b0c0 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  not.** completed
2b0d0 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
2b0e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2b0f0 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
2b100 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
2b110 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
2b120 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
2b130 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
2b140 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65  pt]..** Incomple
2b150 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
2b160 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
2b170 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
2b180 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65  anceled,.** depe
2b190 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72  nding on the cir
2b1a0 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20  cumstances, and 
2b1b0 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  the.** [error co
2b1c0 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
2b1d0 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
2b1e0 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  RT]..**.** INVAR
2b1f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2b200 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1302} The [sqlit
2b210 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
2b220 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f  interface destro
2b230 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ys the.**       
2b240 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2b250 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65  tement] S and re
2b260 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20  leases all.**   
2b270 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e         memory an
2b280 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73  d file resources
2b290 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62   held by that ob
2b2a0 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ject..**.** {H11
2b2b0 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  304} If the most
2b2c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2b2d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2b2e0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ] for the.**    
2b2f0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2b300 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
2b310 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a  urned an error,.
2b320 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2b330 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b340 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74  ze(S)] returns t
2b350 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a  hat same error..
2b360 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
2b370 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2b380 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2b3a0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2b3b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2b3c0 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30   {H13330} <S7030
2b3d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2b3e0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2b3f0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2b400 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2b410 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2b420 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2b430 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2b440 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2b450 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2b460 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
2b470 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
2b480 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
2b490 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
2b4a0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2b4b0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2b4c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
2b4d0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
2b4e0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
2b4f0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2b500 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
2b510 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
2b520 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20  .**.** {H11332} 
2b530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2b540 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2b550 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2b560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b570 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
2b580 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
2b590 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
2b5a0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ram..**.** {H113
2b5b0 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} If the most 
2b5c0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2b5d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b5e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2b5f0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2b600 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2b610 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2b620 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2b630 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
2b640 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2b650 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2b660 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2b670 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
2b680 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
2b690 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2b6a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2b6b0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  K]..**.** {H1133
2b6c0 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
2b6d0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2b6e0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b6f0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2b700 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2b710 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2b720 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2b730 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
2b740 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b750 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2b760 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2b770 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48   code]..**.** {H
2b780 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69  11338} The [sqli
2b790 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2b7a0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
2b7b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
2b7c0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
2b7d0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2b7e0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2b7f0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2b800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b810 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b820 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2b830 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2b850 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2b860 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
2b870 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H16100} <S20200>
2b880 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
2b890 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2b8a0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
2b8b0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2b8c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b8d0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
2b8e0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2b8f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b900 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2b910 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63  * These two func
2b920 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2b930 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2b940 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2b950 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2b960 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2b970 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2b980 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2b990 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2b9a0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2b9b0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2b9c0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2b9d0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2b9e0 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
2b9f0 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
2ba00 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
2ba10 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
2ba20 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
2ba30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2ba40 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
2ba50 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
2ba60 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2ba70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
2ba80 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
2ba90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2baa0 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
2bab0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2bac0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2bad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bae0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2baf0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2bb00 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2bb10 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f   If a single pro
2bb20 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
2bb30 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
2bb40 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
2bb50 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
2bb60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2bb70 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
2bb80 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65  vidually to.** e
2bb90 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2bba0 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  nection..**.** T
2bbb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2bbc0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2bbd0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2bbe0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2bbf0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2bc00 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  d.  The length o
2bc10 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2bc20 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2bc30 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
2bc40 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
2bc50 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
2bc60 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
2bc70 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2bc80 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
2bc90 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
2bca0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2bcb0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2bcc0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2bcd0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2bce0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2bcf0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
2bd00 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
2bd10 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2bd20 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2bd30 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2bd40 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2bd50 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2bd60 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65  . If this parame
2bd70 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
2bd80 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2bd90 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2bda0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2bdb0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2bdc0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
2bdd0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2bde0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2bdf0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2be00 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2be10 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2be20 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2be30 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2be40 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2be50 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
2be60 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2be70 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
2be80 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
2be90 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2bea0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2beb0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2bec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2bed0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2bee0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2bef0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2bf00 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c  ther.  It is all
2bf10 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  owed to.** invok
2bf20 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2bf30 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2bf40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bf50 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2bf60 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2bf70 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2bf80 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2bf90 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2bfa0 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68   eTextRep..** Wh
2bfb0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2bfc0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2bfd0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2bfe0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2bff0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2c000 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2c010 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2c020 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2c030 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2c040 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2c050 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2c060 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2c070 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2c080 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2c090 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2c0a0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2c0b0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2c0c0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2c0d0 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70  *.** The fifth p
2c0e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2c0f0 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2c100 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2c110 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2c120 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2c130 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2c140 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2c150 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2c160 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  a()]..**.** The 
2c170 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
2c180 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
2c190 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
2c1a0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
2c1b0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
2c1c0 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
2c1d0 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
2c1e0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2c1f0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2c200 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72  regate. A scalar
2c210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2c220 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2c230 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2c240 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
2c250 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69  k only, NULL poi
2c260 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
2c270 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2c280 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
2c290 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e  * parameters. An
2c2a0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2c2b0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2c2c0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2c2d0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
2c2e0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
2c2f0 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
2c300 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54  sed for xFunc. T
2c310 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2c320 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2c330 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2c340 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
2c350 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
2c360 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  ion callbacks..*
2c370 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
2c380 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
2c390 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2c3a0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2c3b0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
2c3c0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
2c3d0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
2c3e0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
2c3f0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
2c400 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
2c410 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
2c420 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
2c430 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2c440 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2c450 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
2c460 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2c470 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2c480 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2c490 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
2c4a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2c4b0 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73   {H16103} The [s
2c4c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c4d0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65  nction16()] inte
2c4e0 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78  rface behaves ex
2c4f0 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  actly.**        
2c500 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f    like [sqlite3_
2c510 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c520 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
2c530 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
2c540 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2c550 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74  prets the zFunct
2c560 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ionName argument
2c570 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   as zero-termina
2c580 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20  ted UTF-16.**   
2c590 20 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79         native by
2c5a0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
2c5b0 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d   of as zero-term
2c5c0 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a  inated UTF-8..**
2c5d0 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73  .** {H16106} A s
2c5e0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
2c5f0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
2c600 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
2c610 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c620 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69  (D,X,N,E,...)] i
2c630 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2c640 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  rs.**          o
2c650 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62  r replaces callb
2c660 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e  ack functions in
2c670 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2c680 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2c690 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f           used to
2c6a0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2c6b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
2c6c0 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d  d X with N param
2c6d0 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
2c6e0 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70    and having a p
2c6f0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2c700 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a  coding of E..**.
2c710 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75  ** {H16109} A su
2c720 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2c730 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c740 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2c750 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
2c760 20 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73          replaces
2c770 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e   the P, F, S, an
2c780 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  d L values from 
2c790 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
2c7a0 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2c7b0 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20   the same D, X, 
2c7c0 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e  N, and E values.
2c7d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20  .**.** {H16112} 
2c7e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2c7f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2c800 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2c810 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20   fails with.**  
2c820 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
2c830 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2c840 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53  _ERROR] if the S
2c850 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
2c860 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   X is.**        
2c870 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35    longer than 25
2c880 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76  5 bytes exclusiv
2c890 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65  e of the zero te
2c8a0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
2c8b0 7b 48 31 36 31 31 38 7d 20 45 69 74 68 65 72 20  {H16118} Either 
2c8c0 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61  F must be NULL a
2c8d0 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e  nd S and L are n
2c8e0 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  on-NULL or else 
2c8f0 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  F.**          is
2c900 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20   non-NULL and S 
2c910 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20  and L are NULL, 
2c920 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20  otherwise.**    
2c930 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2c940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c950 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2c960 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2c970 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _ERROR]..**.** {
2c980 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  H16121} The [sql
2c990 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c9a0 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  tion(D,...)] int
2c9b0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2c9c0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
2c9d0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
2c9e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20  SQLITE_BUSY] if 
2c9f0 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65  there exist [pre
2ca00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ca10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
2ca20 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2ca30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ca40 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2ca50 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73   {H16124} The [s
2ca60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ca70 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
2ca80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2ca90 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2caa0 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2cab0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52  e of [SQLITE_ERR
2cac0 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72  OR] if parameter
2cad0 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74   N (specifying t
2cae0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  he number.**    
2caf0 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e        of argumen
2cb00 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
2cb10 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67  nction being reg
2cb20 69 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73  istered) is less
2cb30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
2cb40 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2cb50 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20  than 127..**.** 
2cb60 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20  {H16127} When N 
2cb70 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2cb80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2cb90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2cba0 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2cbb0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
2cbc0 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73  causes callbacks
2cbd0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66   to be invoked f
2cbe0 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  or the SQL funct
2cbf0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
2cc00 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65  named X when the
2cc10 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2cc20 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
2cc30 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  function is.**  
2cc40 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20          exactly 
2cc50 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30  N..**.** {H16130
2cc60 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20  } When N is -1, 
2cc70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2cc80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2cc90 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2cca0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
2ccb0 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
2ccc0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2ccd0 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
2cce0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
2ccf0 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20  amed X with any 
2cd00 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2cd10 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  nts..**.** {H161
2cd20 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74  33} When calls t
2cd30 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2cd40 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2cd50 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2cd60 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2cd70 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2cd80 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2cd90 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20  function X.**   
2cda0 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20         and when 
2cdb0 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  one implementati
2cdc0 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20  on has N>=0 and 
2cdd0 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d  the other has N=
2cde0 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  (-1).**         
2cdf0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2ce00 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ion with a non-z
2ce10 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72  ero N is preferr
2ce20 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ed..**.** {H1613
2ce30 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  6} When calls to
2ce40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ce50 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ce60 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  E,...)].**      
2ce70 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74      specify mult
2ce80 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2ce90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2cea0 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
2ceb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2cec0 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20   same number of 
2ced0 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20  arguments N but 
2cee0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a  with different.*
2cef0 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64  *          encod
2cf00 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65  ings E, then the
2cf10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2cf20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20  where E matches 
2cf30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cf40 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2cf50 67 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a  g is preferred..
2cf60 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46  **.** {H16139} F
2cf70 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  or an aggregate 
2cf80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65  SQL function cre
2cf90 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
2cfa0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2cfb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2cfc0 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29  D,X,N,E,P,0,S,L)
2cfd0 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a  ] the finalizer.
2cfe0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
2cff0 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61  tion L will alwa
2d000 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78  ys be invoked ex
2d010 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68  actly once if th
2d020 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  e.**          st
2d030 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73  ep function S is
2d040 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2d050 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a  ore times..**.**
2d060 20 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53   {H16142} When S
2d070 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69  QLite invokes ei
2d080 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f  ther the xFunc o
2d090 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e  r xStep function
2d0a0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2d0b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
2d0c0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d0d0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2d0e0 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20   created.**     
2d0f0 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
2d100 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d110 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d120 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d130 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
2d140 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79    then the array
2d150 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2d160 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73  ue] objects pass
2d170 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20  ed as the.**    
2d180 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61        third para
2d190 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73  meter are always
2d1a0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2d1b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d1c0 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ts..*/.int sqlit
2d1d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d1e0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2d1f0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2d200 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2d210 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2d220 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2d230 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2d240 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2d250 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d260 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d270 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2d280 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d290 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2d2a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2d2b0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2d2c0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2d2d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2d2e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2d2f0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2d300 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2d310 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2d320 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2d330 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2d340 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2d350 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2d360 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2d370 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2d380 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2d390 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2d3a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2d3b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2d3c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2d3d0 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t*).);../*.** CA
2d3e0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2d3f0 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20  odings {H10267} 
2d400 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30  <S50200> <H16100
2d410 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  >.**.** These co
2d420 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
2d430 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
2d440 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
2d450 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
2d460 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
2d470 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
2d480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d490 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
2d4a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d4b0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
2d4c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d4d0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
2d4e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d4f0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
2d500 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
2d510 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
2d520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2d530 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
2d540 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2d550 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
2d560 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
2d570 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2d580 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
2d590 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2d5a0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
2d5b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2d5c0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
2d5d0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
2d5e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2d5f0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
2d600 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
2d610 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
2d620 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
2d630 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
2d640 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
2d650 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
2d660 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
2d670 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
2d680 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
2d690 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
2d6a0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
2d6b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2d6c0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
2d6d0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
2d6e0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
2d6f0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
2d700 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
2d710 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74   tell you want t
2d720 68 65 79 20 64 6f 2e 0a 2a 2f 0a 53 51 4c 49 54  hey do..*/.SQLIT
2d730 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2d740 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2d750 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2d760 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2d770 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2d780 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2d790 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2d7a0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2d7b0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2d7c0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2d7d0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2d7e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2d7f0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2d800 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
2d810 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2d820 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
2d830 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
2d840 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
2d850 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
2d860 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2d870 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
2d880 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
2d890 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2d8a0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
2d8b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  te3_int64);../*.
2d8c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2d8d0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
2d8e0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
2d8f0 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53  lues {H15100} <S
2d900 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
2d910 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2d920 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2d930 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2d940 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2d950 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2d960 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2d970 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2d980 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2d990 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2d9a0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2d9b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2d9c0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2d9d0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2d9e0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2d9f0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2da00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2da10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2da20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2da30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2da40 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2da50 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2da60 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2da70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2da80 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
2da90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2daa0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
2dab0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
2dac0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2dad0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2dae0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2daf0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2db00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2db10 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2db20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2db30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2db40 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2db50 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2db60 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2db70 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2db80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2db90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2dba0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2dbb0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2dbc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2dbd0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2dbe0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2dbf0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2dc00 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2dc10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2dc20 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2dc30 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2dc40 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  avior..**.** The
2dc50 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2dc60 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2dc70 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2dc80 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2dc90 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2dca0 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2dcb0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2dcc0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2dcd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2dce0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2dcf0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2dd00 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2dd10 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2dd20 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2dd30 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
2dd40 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2dd50 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
2dd60 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
2dd70 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2dd80 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2dd90 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2dda0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
2ddb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ddc0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2ddd0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2dde0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2ddf0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2de00 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2de10 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2de20 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2de30 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  ctively..**.** T
2de40 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2de50 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
2de60 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2de70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
2de80 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
2de90 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
2dea0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
2deb0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
2dec0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
2ded0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
2dee0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
2def0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
2df00 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
2df10 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
2df20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
2df30 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
2df40 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
2df50 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
2df60 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
2df70 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
2df80 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
2df90 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
2dfa0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
2dfb0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
2dfc0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
2dfd0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2dfe0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2dff0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2e000 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2e010 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2e020 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2e030 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2e040 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
2e050 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
2e060 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2e070 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2e080 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2e090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2e0a0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2e0b0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2e0c0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2e0d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e0e0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2e0f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2e100 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2e110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e120 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2e130 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e140 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
2e150 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2e160 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2e170 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2e180 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2e190 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2e1a0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2e1b0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2e1c0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ters..**.** INVA
2e1d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2e1e0 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  15103} The [sqli
2e1f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
2e200 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2e210 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2e220 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e230 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e240 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2e250 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a  BLOB and then.**
2e260 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2e270 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2e280 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
2e290 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  ue..**.** {H1510
2e2a0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2e2b0 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20  value_bytes(V)] 
2e2c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e2d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2e2e0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2e2f0 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72  s in the BLOB or
2e300 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2e310 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2e320 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2e330 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2e340 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2e350 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2e360 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2e370 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2e380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2e390 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  b(V)] or.**     
2e3a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2e3b0 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a  lue_text(V)]..**
2e3c0 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65  .** {H15109} The
2e3d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e3e0 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65  bytes16(V)] inte
2e3f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2e400 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2e410 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e420 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
2e430 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2e440 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2e450 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2e460 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2e470 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2e480 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2e490 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2e4a0 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
2e4b0 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20  _text16(V)],.** 
2e4c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2e4d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2e4e0 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  (V)], or [sqlite
2e4f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2e500 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  (V)]..**.** {H15
2e510 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  112} The [sqlite
2e520 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56  3_value_double(V
2e530 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2e540 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2e550 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e560 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e570 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2e580 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2e590 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
2e5a0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2e5b0 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
2e5c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35  e..**.** {H15115
2e5d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2e5e0 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74  alue_int(V)] int
2e5f0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2e600 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e610 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2e620 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e630 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   V into a 64-bit
2e640 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2e650 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2e660 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
2e670 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
2e680 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
2e690 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73   {H15118} The [s
2e6a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2e6b0 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  64(V)] interface
2e6c0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2e6d0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2e6e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e6f0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2e700 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2e710 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2e720 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2e730 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
2e740 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2e750 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71  {H15121} The [sq
2e760 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e770 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2e780 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2e790 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2e7a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e7b0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2e7c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2e7d0 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  d UTF-8.**      
2e7e0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2e7f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e800 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2e810 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20  .**.** {H15124} 
2e820 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2e830 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e  ue_text16(V)] in
2e840 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2e850 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e860 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2e870 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e880 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
2e890 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2e8a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2e8b0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
2e8c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
2e8d0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2e8e0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2e8f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2e900 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2e910 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  15127} The [sqli
2e920 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e930 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  be(V)] interface
2e940 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2e950 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2e960 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e970 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2e980 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2e990 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2e9a0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2e9b0 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
2e9c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2e9d0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
2e9e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2e9f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2ea00 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71  {H15130} The [sq
2ea10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ea20 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61  16le(V)] interfa
2ea30 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2ea40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2ea50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ea60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2ea70 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2ea80 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2ea90 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2eaa0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
2eab0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2eac0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2ead0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2eae0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2eaf0 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68  *.** {H15133} Th
2eb00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2eb10 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
2eb20 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
2eb30 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b          one of [
2eb40 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53  SQLITE_NULL], [S
2eb50 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
2eb60 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a  [SQLITE_FLOAT],.
2eb70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2eb80 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53  ITE_TEXT], or [S
2eb90 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
2eba0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
2ebb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2ebc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ebd0 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
2ebe0 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c  H15136} The [sql
2ebf0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2ec00 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ic_type(V)] inte
2ec10 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a  rface converts.*
2ec20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2ec30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ec40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ec50 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e  V into either an
2ec60 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20   integer or.**  
2ec70 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69          a floati
2ec80 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69  ng point value i
2ec90 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77  f it can do so w
2eca0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a  ithout loss of.*
2ecb0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72  *          infor
2ecc0 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75  mation, and retu
2ecd0 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  rns one of [SQLI
2ece0 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20  TE_NULL],.**    
2ecf0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e        [SQLITE_IN
2ed00 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2ed10 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2ed20 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  TEXT], or.**    
2ed30 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c        [SQLITE_BL
2ed40 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2ed50 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  te for the.**   
2ed60 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2ed70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ed80 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20   object V after 
2ed90 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  the conversion a
2eda0 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  ttempt..*/.const
2edb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2edc0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
2edd0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2ede0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2edf0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
2ee00 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2ee10 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
2ee20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
2ee30 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
2ee40 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
2ee50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2ee60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2ee70 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2ee80 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2ee90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2eea0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
2eeb0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
2eec0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2eed0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
2eee0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2eef0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ef00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2ef10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ef20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ef30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ef40 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
2ef50 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2ef60 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2ef70 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2ef80 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2ef90 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2efa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2efb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2efc0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2efd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2efe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2eff0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
2f000 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
2f010 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32  ext {H16210} <S2
2f020 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
2f030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2f040 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2f050 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2f060 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  is routine to al
2f070 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75  locate.** a stru
2f080 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e  cture for storin
2f090 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
2f0a0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74  *.** The first t
2f0b0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
2f0c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f0d0 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  t() routine is c
2f0e0 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70  alled for a.** p
2f0f0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2f100 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f  ate, SQLite allo
2f110 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20  cates nBytes of 
2f120 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
2f130 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72  ut that.** memor
2f140 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
2f150 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
2f160 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
2f170 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2f180 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
2f190 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2f1a0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
2f1b0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2f1c0 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73   index,.** the s
2f1d0 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
2f1e0 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c  turned. The impl
2f1f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2f200 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20  e aggregate can 
2f210 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  use.** the retur
2f220 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63  ned buffer to ac
2f230 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a  cumulate data..*
2f240 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f  *.** SQLite auto
2f250 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2f260 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75  the allocated bu
2f270 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67  ffer when the ag
2f280 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79  gregate.** query
2f290 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2f2a0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2f2b0 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
2f2c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2f2d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2f2e0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
2f2f0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
2f300 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
2f310 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
2f320 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
2f330 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2f340 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
2f350 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2f360 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2f370 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2f380 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2f390 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2f3a0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2f3b0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2f3c0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
2f3d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  NTS:.**.** {H162
2f3e0 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e  11} The first in
2f3f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
2f400 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f410 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
2f420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
2f430 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
2f440 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61  ce of an aggrega
2f450 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72  te function (for
2f460 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
2f470 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2f480 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69  t C) causes SQLi
2f490 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e  te to allocate N
2f4a0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
2f4b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  ,.**          ze
2f4c0 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ro that memory, 
2f4d0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
2f4e0 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f  nter to the allo
2f4f0 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  cated memory..**
2f500 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20  .** {H16213} If 
2f510 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2f520 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
2f530 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   during.**      
2f540 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67      [sqlite3_agg
2f550 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2f560 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75  ,N)] then the fu
2f570 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
2f580 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d  ..**.** {H16215}
2f590 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   Second and subs
2f5a0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2f5b0 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ns of.**        
2f5c0 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65    [sqlite3_aggre
2f5d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2f5e0 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  )] for the same 
2f5f0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
2f600 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67  C.**          ig
2f610 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d  nore the N param
2f620 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20  eter and return 
2f630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2f640 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
2f650 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72    block of memor
2f660 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  y returned by th
2f670 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
2f680 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31  on..**.** {H1621
2f690 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  7} The memory al
2f6a0 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69  located by [sqli
2f6b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f6c0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a  ntext(C,N)] is.*
2f6d0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2f6e0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f  atically freed o
2f6f0 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  n the next call 
2f700 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2f710 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
2f720 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2f730 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65  alize()] for the
2f740 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f750 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67  ment] containing
2f760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2f770 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2f780 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2f790 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a  ith context C..*
2f7a0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2f7b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f7c0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2f7d0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
2f7e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f7f0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
2f800 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34  Functions {H1624
2f810 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
2f820 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
2f830 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
2f840 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2f850 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2f860 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
2f870 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
2f880 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
2f890 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2f8a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2f8b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2f8c0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2f8d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f8e0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2f8f0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2f900 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2f910 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2f920 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
2f930 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
2f940 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2f950 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2f960 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2f970 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
2f980 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f990 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2f9a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2f9b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
2f9c0 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  243} The [sqlite
2f9d0 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20  3_user_data(C)] 
2f9e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f9f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2fa00 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 6f  **          P po
2fa10 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
2fa20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fa30 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2fa40 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
2fa50 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2fa60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fa70 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
2fa80 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
2fa90 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
2faa0 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
2fab0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
2fac0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2fad0 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
2fae0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
2faf0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
2fb00 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2fb10 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
2fb20 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
2fb30 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  For Functions {H
2fb40 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c  16250} <S60600><
2fb50 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2fb60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2fb70 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2fb80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2fb90 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2fba0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2fbb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fbc0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2fbd0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2fbe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2fbf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2fc00 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2fc10 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fc20 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2fc30 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2fc40 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2fc50 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2fc60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
2fc70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2fc80 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54  **.** {H16253} T
2fc90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2fca0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29  ext_db_handle(C)
2fcb0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2fcc0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2fcd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20  e.**          D 
2fce0 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65  pointer from the
2fcf0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2fd00 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2fd10 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
2fd20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2fd30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fd40 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ion16(D,X,N,E,P,
2fd50 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61  F,S,L)] call tha
2fd60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  t.**          re
2fd70 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c  gistered the SQL
2fd80 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
2fd90 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  ated with [sqlit
2fda0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
2fdb0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2fdc0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2fdd0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
2fde0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2fdf0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
2fe00 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
2fe10 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30   {H16270} <S2020
2fe20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  0>.**.** The fol
2fe30 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2fe40 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2fe50 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2fe60 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2fe70 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2fe80 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2fe90 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2fea0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2feb0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2fec0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2fed0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2fee0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2fef0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2ff00 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2ff10 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2ff20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2ff30 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2ff40 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2ff50 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2ff60 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2ff70 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2ff80 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2ff90 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2ffa0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2ffb0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2ffc0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2ffd0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2ffe0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2fff0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
30000 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
30010 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
30020 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
30030 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
30040 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
30050 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
30060 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
30070 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
30080 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
30090 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
300a0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
300b0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
300c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
300d0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
300e0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
300f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
30100 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
30110 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30120 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
30130 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
30140 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
30150 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30160 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
30170 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
30180 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
30190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
301a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
301b0 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   If no metadata 
301c0 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
301d0 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
301e0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
301f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
30200 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
30210 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
30220 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
30230 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
30240 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
30250 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
30260 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30270 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
30280 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
30290 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
302a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
302b0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
302c0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
302d0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
302e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
302f0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
30300 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
30310 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
30320 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30330 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
30340 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
30350 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
30360 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
30370 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
30380 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
30390 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
303a0 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f  ..** If it is no
303b0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
303c0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
303d0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
303e0 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
303f0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
30400 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
30410 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
30420 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
30430 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
30440 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
30450 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
30460 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
30470 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
30480 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
30490 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
304a0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
304b0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
304c0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
304d0 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
304e0 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
304f0 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
30500 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68  at any time.  Th
30510 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
30520 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
30530 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
30540 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
30550 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
30560 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
30570 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
30580 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
30590 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
305a0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
305b0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
305c0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
305d0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
305e0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
305f0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
30600 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65  and SQL variable
30610 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
30620 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
30630 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30640 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
30650 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
30660 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
30670 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
30680 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
30690 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6272} The [sqlit
306a0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
306b0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
306c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
306d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
306e0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
306f0 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68  ted with the Nth
30700 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
30710 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
30720 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65  *          whose
30730 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f   context is C, o
30740 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20  r NULL if there 
30750 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61  is no metadata a
30760 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20  ssociated.**    
30770 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20        with that 
30780 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
30790 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73   {H16274} The [s
307a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
307b0 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74  ta(C,N,P,D)] int
307c0 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61  erface assigns a
307d0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20   metadata.**    
307e0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20        pointer P 
307f0 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  to the Nth param
30800 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
30810 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f  function with co
30820 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b  ntext C..**.** {
30830 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77  H16276} SQLite w
30840 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
30850 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68  estructor D with
30860 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
30870 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
30880 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61  hich is the meta
30890 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66  data pointer P f
308a0 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
308b0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
308c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
308d0 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68  ata(C,N,P,D)] wh
308e0 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  en SQLite ceases
308f0 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20   to hold.**     
30900 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74       the metadat
30910 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37  a..**.** {H16277
30920 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20  } SQLite ceases 
30930 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61  to hold metadata
30940 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63   for an SQL func
30950 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
30960 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
30970 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
30980 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  t parameter chan
30990 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ges..**.** {H162
309a0 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  78} When [sqlite
309b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
309c0 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b  N,P,D)] is invok
309d0 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74  ed, the destruct
309e0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  or.**          i
309f0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79  s called for any
30a00 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20   prior metadata 
30a10 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
30a20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
30a30 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  n.**          co
30a40 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61  ntext C and para
30a50 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  meter N..**.** {
30a60 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77  H16279} SQLite w
30a70 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63  ill call destruc
30a80 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74  tors for any met
30a90 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64  adata it is hold
30aa0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
30ab0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
30ac0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30ad0 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68  ent] S when eith
30ae0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
30af0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
30b00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
30b10 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61  nalize(S)] is ca
30b20 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  lled..*/.void *s
30b30 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30b40 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
30b50 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
30b60 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
30b70 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
30b80 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
30b90 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
30ba0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
30bb0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
30bc0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
30bd0 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
30be0 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30  Behavior {H10280
30bf0 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30100>.**.**
30c00 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
30c10 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
30c20 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
30c30 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
30c40 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
30c50 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
30c60 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
30c70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
30c80 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
30c90 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
30ca0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
30cb0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
30cc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
30cd0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
30ce0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
30cf0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
30d00 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
30d10 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
30d20 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
30d30 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
30d40 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
30d50 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
30d60 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
30d70 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
30d80 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
30d90 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
30da0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
30db0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
30dc0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
30dd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
30de0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
30df0 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
30e00 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
30e10 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
30e20 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
30e30 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
30e40 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
30e50 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
30e60 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
30e70 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
30e80 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
30e90 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
30ea0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
30eb0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
30ec0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
30ed0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
30ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
30ef0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
30f00 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
30f10 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32  ion {H16400} <S2
30f20 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0200>.**.** Thes
30f30 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
30f40 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
30f50 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
30f60 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
30f70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
30f80 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
30f90 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
30fa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30fb0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
30fc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30fd0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
30fe0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
30ff0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
31000 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31010 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
31020 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
31030 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
31040 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
31050 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
31060 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
31070 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
31080 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
31090 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
310a0 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
310b0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
310c0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
310d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
310e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
310f0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
31100 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31110 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
31120 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31130 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
31140 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
31150 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
31160 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
31170 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
31180 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
31190 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
311a0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
311b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
311c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
311d0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
311e0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
311f0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
31200 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
31210 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31220 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
31230 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
31240 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
31250 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
31260 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
31270 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31280 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
31290 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
312a0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
312b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
312c0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
312d0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
312e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
312f0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
31300 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
31310 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
31320 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
31330 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
31340 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31350 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
31360 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31370 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
31380 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
31390 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
313a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
313b0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74  eption..** SQLit
313c0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
313d0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
313e0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
313f0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
31400 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
31410 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
31420 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
31430 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
31440 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
31450 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
31460 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
31470 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
31480 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
31490 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
314a0 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  -8. SQLite.** in
314b0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
314c0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
314d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
314e0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
314f0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
31500 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
31510 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
31520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31530 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
31540 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31550 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
31560 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
31570 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
31580 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
31590 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
315a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
315b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
315c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
315d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
315e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
315f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
31600 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
31610 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
31620 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
31630 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
31640 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
31650 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
31660 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
31670 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
31680 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31690 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
316a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
316b0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
316c0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
316d0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
316e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
316f0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
31700 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
31710 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
31720 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
31730 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
31740 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
31750 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
31760 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
31770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
31780 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
31790 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
317a0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
317b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
317c0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
317d0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
317e0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42  n a function.  B
317f0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
31800 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
31810 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41  SQLITE_ERROR.  A
31820 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
31830 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
31840 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
31850 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31860 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
31870 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
31880 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
31890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
318a0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
318b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
318c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
318d0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
318e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
318f0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
31900 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72   is to long to r
31910 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
31920 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31930 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
31940 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
31950 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
31960 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
31970 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
31980 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
31990 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
319a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
319b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
319c0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
319d0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
319e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
319f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31a00 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
31a10 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31a20 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
31a30 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31a40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
31a50 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
31a60 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31a70 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
31a80 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31a90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31aa0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
31ab0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31ac0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
31ad0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
31ae0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
31af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31b00 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
31b10 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
31b20 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
31b30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31b40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
31b50 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
31b60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31b70 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
31b80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31b90 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
31ba0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
31bb0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
31bc0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
31bd0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
31be0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
31bf0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
31c00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31c10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
31c20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
31c30 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
31c40 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
31c50 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
31c60 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
31c70 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
31c80 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
31c90 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
31ca0 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61  ly..** SQLite ta
31cb0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
31cc0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
31cd0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
31ce0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31cf0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
31d00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31d10 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66  nterfaces..** If
31d20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
31d30 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
31d40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31d50 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
31d60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
31d70 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
31d80 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
31d90 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
31da0 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
31db0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
31dc0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
31dd0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
31de0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31df0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
31e00 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
31e10 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
31e20 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
31e30 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
31e40 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
31e50 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
31e60 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
31e70 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
31e80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
31e90 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
31ea0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
31eb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31ec0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31ed0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31ee0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
31ef0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
31f00 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
31f10 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
31f20 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
31f30 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
31f40 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
31f50 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
31f60 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
31f70 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
31f80 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
31f90 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
31fa0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31fb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31fc0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a  * interfaces or.
31fd0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
31fe0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
31ff0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
32000 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
32010 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
32020 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
32030 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
32040 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
32050 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
32060 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
32070 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  it or call a des
32080 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
32090 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
320a0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
320b0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
320c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
320d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
320e0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
320f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
32100 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
32110 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
32120 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
32130 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
32140 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
32150 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
32160 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
32170 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
32180 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
32190 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
321a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
321b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
321c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
321d0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
321e0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
321f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32200 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
32210 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
32220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
32240 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
32250 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
32260 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
32270 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
32280 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
32290 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
322a0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
322b0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
322c0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
322d0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
322e0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
322f0 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
32300 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
32310 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
32320 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
32330 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74  harm..** A [prot
32340 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32350 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
32360 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
32370 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
32380 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32390 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
323a0 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
323b0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
323c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
323d0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
323e0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
323f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
32400 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32410 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
32420 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
32430 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
32440 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
32450 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
32460 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32470 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
32480 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
32490 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
324a0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
324b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
324c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
324d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  NTS:.**.** {H164
324e0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
324f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
32500 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
32510 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
32520 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b  * {H16406} The [
32530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32540 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
32550 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32560 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32570 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32580 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32590 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20   a BLOB that is 
325a0 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
325b0 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
325c0 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
325d0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
325e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54  **.** {H16409} T
325f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32600 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
32610 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32620 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32630 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32640 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32650 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
32660 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
32670 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68  *.** {H16412} Th
32680 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32690 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
326a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
326b0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
326c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
326d0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
326e0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
326f0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
32700 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
32710 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
32720 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73   UTF-8 error mes
32730 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d  sage copied from
32740 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20   V up to the.** 
32750 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a           first z
32760 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69  ero byte or unti
32770 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65  l N bytes are re
32780 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
32790 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
327a0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
327b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
327c0 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
327d0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
327e0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
327f0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32800 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
32810 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
32820 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
32830 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
32840 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  R] and a UTF-16 
32850 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32860 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  r error message.
32870 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69  **          copi
32880 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
32890 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
328a0 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74  erminator or unt
328b0 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20  il N bytes.**   
328c0 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20         are read 
328d0 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
328e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d  ..**.** {H16418}
328f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32900 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
32910 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  g(C)] interface 
32920 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
32930 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
32940 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
32950 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
32960 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
32970 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
32980 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f        [SQLITE_TO
32990 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70  OBIG] and an app
329a0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
329b0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
329c0 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16421} The [sqli
329d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
329e0 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72  _nomem(C)] inter
329f0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
32a00 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
32a10 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65      value of the
32a20 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32a30 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
32a40 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
32a50 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
32a60 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e  TE_NOMEM] and an
32a70 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
32a80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
32a90 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b  * {H16424} The [
32aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32ab0 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20  rror_code(C,E)] 
32ac0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32ad0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
32ae0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
32af0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
32b00 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
32b10 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
32b20 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20  ode E..**       
32b30 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73     The error mes
32b40 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63  sage text is unc
32b50 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanged..**.** {H
32b60 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16427} The [sqli
32b70 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43  te3_result_int(C
32b80 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
32b90 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32ba0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
32bb0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32bc0 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  C to be the 32-b
32bd0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  it integer value
32be0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33   V..**.** {H1643
32bf0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
32c00 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56  result_int64(C,V
32c10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32c20 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32c30 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32c40 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32c50 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
32c60 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
32c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d  ..**.** {H16433}
32c80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32c90 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e  sult_null(C)] in
32ca0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32cb0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32cc0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32cd0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32ce0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
32cf0 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  6436} The [sqlit
32d00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
32d10 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
32d20 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
32d30 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
32d40 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
32d50 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
32d60 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
32d70 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74 6f           V up to
32d80 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
32d90 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
32da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
32db0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
32dc0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
32dd0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
32de0 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20  ** {H16439} The 
32df0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32e00 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
32e10 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32e20 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
32e30 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32e40 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32e50 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e   be the UTF-16 n
32e60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
32e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
32e80 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
32e90 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
32ea0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
32eb0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
32ec0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
32ed0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
32ee0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
32ef0 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16442} The [sqli
32f00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32f10 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6be(C,V,N,D)] in
32f20 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32f30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32f40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32f50 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32f60 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d   the UTF-16 big-
32f70 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
32f80 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
32f90 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
32fa0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
32fb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
32fc0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
32fd0 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20  es or V if N is 
32fe0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
32ff0 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65  .** {H16445} The
33000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33010 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
33020 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
33030 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
33040 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
33050 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
33060 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31   to be the UTF-1
33070 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
33080 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
33090 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  ng V up to the f
330a0 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
330b0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
330c0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
330d0 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
330e0 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
330f0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
33100 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  6448} The [sqlit
33110 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
33120 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
33130 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
33140 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
33150 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
33160 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e   C to be the [un
33170 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33180 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20  3_value].**     
33190 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a       object V..*
331a0 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68  *.** {H16451} Th
331b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
331c0 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d  t_zeroblob(C,N)]
331d0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
331e0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
331f0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
33200 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
33210 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c   be an N-byte BL
33220 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e  OB of all zeros.
33230 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20  .**.** {H16454} 
33240 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33250 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64  ult_error()] and
33260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33270 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20  _error16()].**  
33280 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
33290 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  es make a copy o
332a0 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65  f their error me
332b0 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62 65  ssage strings be
332c0 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  fore.**         
332d0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
332e0 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68  * {H16457} If th
332f0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
33300 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
33310 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33320 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
33330 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
33340 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
33350 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
33360 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
33370 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
33380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33390 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
333a0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
333b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
333c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
333d0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74  e(C,V,N,D)] is t
333e0 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c  he constant [SQL
333f0 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20  ITE_STATIC].**  
33400 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20          then no 
33410 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65 76  destructor is ev
33420 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  er called on the
33430 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53   pointer V and S
33440 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  QLite.**        
33450 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 56    assumes that V
33460 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a   is immutable..*
33470 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66  *.** {H16460} If
33480 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
33490 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
334a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
334b0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
334c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
334d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
334e0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
334f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33500 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
33510 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33520 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
33530 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
33540 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
33550 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33560 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
33570 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a  s the constant.*
33580 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
33590 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68  TE_TRANSIENT] th
335a0 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  en the interface
335b0 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  s makes a copy o
335c0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
335d0 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61    content of V a
335e0 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20 63  nd retains the c
335f0 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  opy..**.** {H164
33600 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  63} If the D des
33610 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
33620 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
33630 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
33640 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
33650 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33660 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
33670 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33680 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
33690 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
336a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
336b0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
336c0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
336d0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
336e0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
336f0 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c  ,D)] is some val
33700 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
33710 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f            the co
33720 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
33730 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c  STATIC] and [SQL
33740 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
33750 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
33760 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
33770 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
33780 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74  r D with V as it
33790 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a  s only argument.
337a0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
337b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
337c0 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75   with the V valu
337d0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
337e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
337f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33800 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33810 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
33820 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
33830 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
33840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33850 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
33860 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33870 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
33880 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
33890 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
338a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
338b0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
338c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
338d0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
338e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
338f0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
33900 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
33910 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33920 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
33930 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33940 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33950 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
33960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33970 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
33980 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
33990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
339a0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
339b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
339c0 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
339d0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
339e0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
339f0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
33a00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33a10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33a20 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
33a30 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33a40 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
33a50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33a60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33a70 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
33a80 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33a90 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
33aa0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33ab0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33ac0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
33ad0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
33ae0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
33af0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
33b00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33b10 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
33b20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33b30 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
33b40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
33b50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33b60 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
33b70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
33b80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
33b90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33ba0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
33bb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33bc0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
33bd0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
33be0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
33bf0 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32  ces {H16600} <S2
33c00 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0300>.**.** Thes
33c10 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
33c20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20  used to add new 
33c30 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33c40 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64  ces to the.** [d
33c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33c60 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
33c70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
33c80 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ent..**.** The n
33c90 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63  ame of the new c
33ca0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33cb0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61  e is specified a
33cc0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
33cd0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
33ce0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33cf0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
33d00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33d10 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
33d20 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20  F-16 string for 
33d30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33d40 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e  ollation16(). In
33d50 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
33d60 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
33d70 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
33d80 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
33d90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
33da0 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  d argument may b
33db0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
33dc0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55  stants [SQLITE_U
33dd0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
33de0 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51  _UTF16LE] or [SQ
33df0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
33e00 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
33e10 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
33e20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
33e30 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
33e40 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
33e50 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
33e60 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
33e70 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
33e80 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
33e90 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74  -endian, respect
33ea0 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68  ively. The.** th
33eb0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
33ec0 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
33ed0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
33ee0 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  ] to indicate th
33ef0 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  at.** the routin
33f00 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65  e expects pointe
33f10 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72  rs to 16-bit wor
33f20 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67  d aligned string
33f30 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69  s.** of UTF-16 i
33f40 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
33f50 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e order of the h
33f60 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
33f70 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
33f80 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69   the user suppli
33f90 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  ed routine must 
33fa0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
33fb0 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65   fifth.** argume
33fc0 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55  nt.  If it is NU
33fd0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
33fe0 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
33ff0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
34000 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
34010 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
34020 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
34030 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65  e)..** Each time
34040 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34050 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69   supplied functi
34060 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  on is invoked, i
34070 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61  t is passed.** a
34080 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61  s its first para
34090 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20  meter a copy of 
340a0 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64  the void* passed
340b0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
340c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
340d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
340e0 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  lation() or sqli
340f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34100 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20  tion16()..**.** 
34110 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
34120 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61  guments to the a
34130 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
34140 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20  ied routine are 
34150 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20  two strings,.** 
34160 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64  each represented
34170 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64   by a (length, d
34180 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e  ata) pair and en
34190 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63  coded in the enc
341a0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61  oding.** that wa
341b0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
341c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77  third argument w
341d0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
341e0 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a  n sequence was.*
341f0 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45  * registered. {E
34200 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61  ND}  The applica
34210 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c  tion defined col
34220 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73  lation routine s
34230 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
34240 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f  negative, zero o
34250 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68  r positive if th
34260 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
34270 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20  s less than,.** 
34280 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
34290 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
342a0 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65  cond string. i.e
342b0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
342c0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ING2)..**.** The
342d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
342e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
342f0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
34300 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34310 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  on().** except t
34320 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
34330 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
34340 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
34350 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
34360 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20  collation.  The 
34370 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
34380 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
34390 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
343a0 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
343b0 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
343c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
343d0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
343e0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
343f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34400 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43  ation_v2()..** C
34410 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65  ollations are de
34420 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65  stroyed when the
34430 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
34440 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20   by later calls 
34450 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74  to the.** collat
34460 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
34470 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
34480 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34490 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
344a0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
344b0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
344c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
344d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20  .**.** {H16603} 
344e0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
344f0 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  l to the.**     
34500 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
34510 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34520 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20  2(B,X,E,P,F,D)] 
34530 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20  interface.**    
34540 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20        registers 
34550 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68  function F as th
34560 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
34570 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a  ction used to.**
34580 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d            implem
34590 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20  ent collation X 
345a0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
345b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66   connection] B f
345c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  or.**          d
345d0 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67 20  atabases having 
345e0 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a  encoding E..**.*
345f0 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74  * {H16604} SQLit
34600 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68  e understands th
34610 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e X parameter to
34620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
34630 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34640 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
34650 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72  P,F,D)] as a zer
34660 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
34670 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
34680 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63  tring in which c
34690 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66  ase is ignored f
346a0 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74  or ASCII charact
346b0 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ers and.**      
346c0 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63 61      is significa
346d0 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49  nt for non-ASCII
346e0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
346f0 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63  ** {H16606} Succ
34700 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20  essive calls to 
34710 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34720 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
34730 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
34740 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20         with the 
34750 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20  same values for 
34760 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65  B, X, and E, ove
34770 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75  rride prior valu
34780 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
34790 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a  f P, F, and D..*
347a0 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66  *.** {H16609} If
347b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
347c0 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  D in [sqlite3_cr
347d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
347e0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
347f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
34800 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20  ot NULL then it 
34810 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
34820 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74  rgument P when t
34830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
34840 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34850 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20  n is dropped by 
34860 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  SQLite..**.** {H
34870 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69  16612} A collati
34880 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
34890 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69  ropped when it i
348a0 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  s overloaded..**
348b0 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63  .** {H16615} A c
348c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
348d0 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65  n is dropped whe
348e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
348f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
34900 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20        is closed 
34910 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
34920 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  lose()]..**.** {
34930 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e  H16618} The poin
34940 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65  ter P in [sqlite
34950 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34960 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
34970 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
34980 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
34990 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
349a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
349b0 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20  comparison.**   
349c0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
349d0 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71  F for all subseq
349e0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
349f0 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of F..**.** {H1
34a00 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20  6621} A call to 
34a10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34a20 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c  collation(B,X,E,
34a30 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79  P,F)] is exactly
34a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34a50 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20   same as a call 
34a60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
34a70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34a80 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  )] with.**      
34a90 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72      the same par
34aa0 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55  ameters and a NU
34ab0 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  LL destructor..*
34ac0 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f  *.** {H16624} Fo
34ad0 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74  llowing a [sqlit
34ae0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34af0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
34b00 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
34b10 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68    SQLite uses th
34b20 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
34b30 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20  ction F for all 
34b40 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a  text comparison.
34b50 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72  **          oper
34b60 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64  ations on the [d
34b70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34b80 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61  on] B on text va
34b90 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20  lues that.**    
34ba0 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f        use the co
34bb0 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
34bc0 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20   named X..**.** 
34bd0 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71  {H16627} The [sq
34be0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34bf0 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50  lation16(B,X,E,P
34c00 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73  ,F)] works the s
34c10 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
34c20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  as [sqlite3_crea
34c30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58  te_collation(B,X
34c40 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20  ,E,P,F)] except 
34c50 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
34c60 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e       collation n
34c70 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73 74  ame X is underst
34c80 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ood as UTF-16 in
34c90 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34ca0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
34cb0 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
34cc0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20  .**.** {H16630} 
34cd0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f  When multiple co
34ce0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
34cf0 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  ns are available
34d00 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a   for the same.**
34d10 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
34d20 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51  ing sequence, SQ
34d30 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65  Lite chooses the
34d40 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20   one whose text 
34d50 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20  encoding.**     
34d60 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74 68       requires th
34d70 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
34d80 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  f conversion fro
34d90 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  m the default.**
34da0 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 65            text e
34db0 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64  ncoding of the d
34dc0 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20  atabase..*/.int 
34dd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34de0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
34df0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
34e00 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
34e10 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
34e20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
34e30 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34e40 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34e50 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
34e60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
34e70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34e80 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
34e90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
34ea0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
34eb0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
34ec0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
34ed0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
34ee0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
34ef0 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
34f00 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
34f10 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
34f20 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34f30 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
34f40 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
34f50 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
34f60 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
34f70 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
34f80 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
34f90 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
34fa0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
34fb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
34fc0 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
34fd0 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d  llbacks {H16700}
34fe0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20300>.**.** 
34ff0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
35000 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
35010 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
35020 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
35030 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
35040 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
35050 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35060 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
35070 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
35080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35090 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65  ion] to be calle
350a0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
350b0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
350c0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
350d0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
350e0 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   If the function
350f0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
35100 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
35110 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35120 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
35130 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
35140 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
35150 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
35160 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
35170 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
35180 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33  n UTF-8. {H16703
35190 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  } If sqlite3_col
351a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
351b0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
351c0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
351d0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
351e0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
351f0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20  yte order..** A 
35200 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
35210 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
35220 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61   any existing ca
35230 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
35240 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
35250 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
35260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
35270 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
35280 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
35290 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
352a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
352b0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
352c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
352d0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
352e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
352f0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
35300 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
35310 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
35320 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
35330 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
35340 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
35350 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
35360 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
35370 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
35380 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
35390 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
353a0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
353b0 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
353c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
353d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
353e0 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
353f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
35400 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  e..**.** The cal
35410 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
35420 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
35430 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
35440 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
35450 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35460 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
35470 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35480 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
35490 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
354a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
354b0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
354c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37  NTS:.**.** {H167
354d0 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  02} A successful
354e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
354f0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35500 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20  ed(D,P,F)].**   
35510 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
35520 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35530 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61  ded16(D,P,F)] ca
35540 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  uses.**         
35550 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35560 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20  onnection] D to 
35570 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20  invoke callback 
35580 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20  F with first.** 
35590 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
355a0 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69 74  er P whenever it
355b0 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69   needs a compari
355c0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72  son function for
355d0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63   a.**          c
355e0 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
355f0 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  e that it does n
35600 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a  ot know about..*
35610 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61  *.** {H16704} Ea
35620 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  ch successful ca
35630 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
35640 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
35650 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
35660 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
35670 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
35680 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 63   overrides the c
35690 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72  allback register
356a0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ed.**          o
356b0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
356c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
356d0 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20   by prior calls 
356e0 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  to either.**    
356f0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e        interface.
35700 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20  .**.** {H16706} 
35710 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
35720 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74  requested collat
35730 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73  ing function pas
35740 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  sed in the.**   
35750 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61 6d         4th param
35760 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
35770 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38  back is in UTF-8
35780 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   if the callback
35790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73  .**          was
357a0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
357b0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  g [sqlite3_colla
357c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
357d0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
357e0 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69  s in UTF-16 nati
357f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
35800 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61   the callback wa
35810 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  s.**          re
35820 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
35830 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35840 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
35850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
35860 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
35870 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
35880 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
35890 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
358a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
358b0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
358c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
358d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
358e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
358f0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
35900 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
35910 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
35920 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
35930 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
35940 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
35950 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
35960 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
35970 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
35980 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
35990 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
359a0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
359b0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
359c0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
359d0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
359e0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
359f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
35a00 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
35a10 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
35a20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
35a30 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
35a40 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
35a50 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
35a60 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
35a70 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
35a80 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
35a90 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
35aa0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
35ab0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
35ac0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
35ad0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
35ae0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
35af0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
35b00 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
35b10 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
35b20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
35b30 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
35b40 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
35b50 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35b60 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35b70 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
35b90 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
35ba0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
35bb0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
35bc0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
35bd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
35be0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
35bf0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
35c00 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
35c10 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
35c20 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
35c30 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30   Short Time {H10
35c40 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a  530} <S40410>.**
35c50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
35c60 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
35c70 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
35c80 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
35c90 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
35ca0 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
35cb0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
35cc0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
35cd0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
35ce0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
35cf0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
35d00 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
35d10 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
35d20 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
35d30 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
35d40 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
35d50 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
35d60 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
35d70 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
35d80 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
35d90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
35da0 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
35db0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
35dc0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
35dd0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
35de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ed..**.** SQLite
35df0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
35e00 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
35e10 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
35e20 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
35e30 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
35e40 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
35e50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
35e60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33  TS:.**.** {H1053
35e70 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
35e80 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66  sleep(M)] interf
35e90 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ace invokes the 
35ea0 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20  xSleep.**       
35eb0 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65     method of the
35ec0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
35ed0 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72  3_vfs|VFS] in or
35ee0 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  der to.**       
35ef0 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75     suspend execu
35f00 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72  tion of the curr
35f10 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61  ent thread for a
35f20 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20  t least.**      
35f30 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e      M millisecon
35f40 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33  ds..**.** {H1053
35f50 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
35f60 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66  sleep(M)] interf
35f70 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
35f80 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
35f90 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e        millisecon
35fa0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
35fb0 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f  ally requested o
35fc0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a  f the operating.
35fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74  **          syst
35fe0 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  em, which might 
35ff0 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
36000 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a  he parameter M..
36010 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
36020 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
36030 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
36040 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
36050 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
36060 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20   Files {H10310} 
36070 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49  <S20000>.**.** I
36080 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
36090 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
360a0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
360b0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
360c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
360d0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
360e0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
360f0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
36100 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
36110 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70  SQLite will be p
36120 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
36130 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69  rectory.  If thi
36140 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
36150 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
36160 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
36170 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
36180 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
36190 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
361a0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
361b0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
361c0 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
361d0 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
361e0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
361f0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20  nection].** has 
36200 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74  been opened.  It
36210 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
36220 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
36230 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
36240 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
36250 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
36260 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
36270 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
36280 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
36290 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20  e been call and 
362a0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
362b0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a   thereafter..*/.
362c0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
362d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
362e0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
362f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
36300 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69  t For Auto-Commi
36310 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20  t Mode {H12930} 
36320 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S60200>.** KEYW
36330 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
36340 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  t mode}.**.** Th
36350 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
36360 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
36370 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
36380 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
36390 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
363a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
363b0 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
363c0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
363d0 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
363e0 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ly.  Autocommit 
363f0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
36400 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f  fault..** Autoco
36410 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
36420 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
36430 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
36440 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
36450 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
36460 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
36470 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
36480 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
36490 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
364a0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
364b0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
364c0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
364d0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
364e0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
364f0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
36500 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
36510 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
36520 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
36530 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
36540 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
36550 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
36560 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
36570 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
36580 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
36590 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
365a0 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
365b0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
365c0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
365d0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
365e0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
365f0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
36600 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
36610 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33  TS:.**.** {H1293
36620 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
36630 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44  get_autocommit(D
36640 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36650 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
36660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
36670 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61  o if the [databa
36680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36690 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
366a0 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20   autocommit.**  
366b0 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65          mode, re
366c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
366d0 2a 20 7b 48 31 32 39 33 32 7d 20 41 75 74 6f 63  * {H12932} Autoc
366e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
366f0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
36700 2a 2a 20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f  ** {H12933} Auto
36710 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
36720 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  isabled by a suc
36730 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20  cessful [BEGIN] 
36740 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
36750 20 7b 48 31 32 39 33 34 7d 20 41 75 74 6f 63 6f   {H12934} Autoco
36760 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61  mmit mode is ena
36770 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73  bled by a succes
36780 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  sful [COMMIT] or
36790 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20   [ROLLBACK].**  
367a0 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
367b0 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  t..**.** ASSUMPT
367c0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
367d0 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20  936} If another 
367e0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
367f0 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
36800 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
36810 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  base.**         
36820 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
36830 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
36840 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
36850 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36870 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
36880 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
36890 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
368a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
368b0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
368c0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
368d0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
368e0 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c  ement {H13120} <
368f0 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60600>.**.** Th
36900 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
36910 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
36920 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
36930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36940 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
36950 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
36960 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
36970 73 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  s.  The database
36980 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64   handle returned
36990 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64   by.** sqlite3_d
369a0 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
369b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61  same database ha
369c0 6e 64 6c 65 20 74 68 61 74 20 77 61 73 20 74 68  ndle that was th
369d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
369e0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
369f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
36a00 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
36a10 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
36a20 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
36a30 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
36a40 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
36a50 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lace..**.** INVA
36a60 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36a70 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  13123} The [sqli
36a80 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29  te3_db_handle(S)
36a90 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
36aa0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
36ab0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
36ac0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36ad0 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
36ae0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 20 20  d with the.**   
36af0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
36b00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
36b10 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
36b20 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
36b30 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
36b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
36b50 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
36b60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b  ared statement {
36b70 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e  H13140} <S60600>
36b80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
36b90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
36ba0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
36bb0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
36bc0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
36bd0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
36be0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
36bf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36c00 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74  ] pDb.  If pStmt
36c10 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
36c20 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
36c30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36c40 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
36c50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36c60 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
36c70 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
36c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
36c90 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65  .  If no prepare
36ca0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
36cb0 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
36cc0 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
36cd0 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
36ce0 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
36cf0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
36d00 2a 20 7b 48 31 33 31 34 33 7d 20 49 66 20 44 20  * {H13143} If D 
36d10 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
36d20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
36d30 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  holds one or mor
36d40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e  e.**          un
36d50 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61  finalized [prepa
36d60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
36d70 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  and S is a NULL 
36d80 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20  pointer,.**     
36d90 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
36da0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
36db0 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  S)] routine shal
36dc0 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  l return a point
36dd0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
36de0 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65  o one of the pre
36df0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
36e00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
36e10 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34   D..**.** {H1314
36e20 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61  6} If D is a [da
36e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36e40 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f  n] that holds no
36e50 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20   unfinalized.** 
36e60 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
36e70 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61  ed statements] a
36e80 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  nd S is a NULL p
36e90 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ointer, then.** 
36ea0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36eb0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
36ec0 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
36ed0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
36ee0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
36ef0 31 33 31 34 39 7d 20 49 66 20 53 20 69 73 20 61  13149} If S is a
36f00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36f10 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61  ment] in the [da
36f20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36f30 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
36f40 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68   and S is not th
36f50 65 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  e last prepared 
36f60 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20  statement in D, 
36f70 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
36f80 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
36f90 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
36fa0 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
36fb0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
36fc0 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78        to the nex
36fd0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
36fe0 6d 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20  ment in D after 
36ff0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32  S..**.** {H13152
37000 7d 20 49 66 20 53 20 69 73 20 74 68 65 20 6c 61  } If S is the la
37010 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
37020 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a  tement] in the.*
37030 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
37040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37050 20 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c   D then the [sql
37060 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
37070 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  , S)].**        
37080 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20    routine shall 
37090 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
370a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  inter..**.** ASS
370b0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
370c0 7b 41 31 33 31 35 34 7d 20 54 68 65 20 5b 64 61  {A13154} The [da
370d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
370e0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
370f0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
37100 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e        [sqlite3_n
37110 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
37120 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
37130 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
37140 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63            connec
37150 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
37160 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
37170 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
37180 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74  r..*/.sqlite3_st
37190 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74  mt *sqlite3_next
371a0 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70  _stmt(sqlite3 *p
371b0 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  Db, sqlite3_stmt
371c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
371d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
371e0 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
371f0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
37200 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c  backs {H12950} <
37210 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
37220 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
37230 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
37240 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
37250 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
37260 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
37270 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
37280 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69  saction is commi
37290 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  tted..** Any cal
372a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
372b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
372c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
372d0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
372e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
372f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
37300 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20  rridden..** The 
37310 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37320 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
37330 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
37340 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
37350 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
37360 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
37370 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69  saction is commi
37380 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  tted..** Any cal
37390 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
373a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
373b0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
373c0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
373d0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
373e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
373f0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20  rridden..** The 
37400 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73  pArg argument is
37410 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
37420 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
37430 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
37440 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
37450 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  hook function re
37460 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a  turns non-zero,.
37470 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ** then the comm
37480 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
37490 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
374a0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
374b0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
374c0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
374d0 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72  ered, its.** pAr
374e0 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
374f0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
37500 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
37510 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
37520 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
37530 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
37540 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37550 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
37560 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
37570 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
37580 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
37590 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
375a0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
375b0 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
375c0 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
375d0 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
375e0 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
375f0 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
37600 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
37610 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  cur..** The roll
37620 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
37630 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
37640 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37650 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
37660 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
37670 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
37680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37690 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20   closed..** The 
376a0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
376b0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
376c0 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
376d0 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  n is.** rolled b
376e0 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f  ack because a co
376f0 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65  mmit callback re
37700 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e  turned non-zero.
37710 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b  .** <todo> Check
37720 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e   on this </todo>
37730 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
37740 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31  S:.**.** {H12951
37750 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
37760 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
37770 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
37780 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
37790 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
377a0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
377b0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
377c0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
377d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
377e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
377f0 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  its on the [data
37800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37810 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35   D..**.** {H1295
37820 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
37830 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
37840 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
37850 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
37860 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
37870 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
37880 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65  us call with the
37890 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
378a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a  connection] D,.*
378b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
378c0 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  LL on the first 
378d0 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69  call for a parti
378e0 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63  cular database c
378f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a  onnection D..**.
37900 2a 2a 20 7b 48 31 32 39 35 33 7d 20 45 61 63 68  ** {H12953} Each
37910 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37920 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
37930 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
37940 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
37950 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
37960 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
37970 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49  **.** {H12954} I
37980 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
37990 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
379a0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
379b0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20   is NULL.**     
379c0 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f       then the co
379d0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
379e0 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61  ck is canceled a
379f0 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  nd no callback.*
37a00 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
37a10 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61  voked when a tra
37a20 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
37a30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d  ..**.** {H12955}
37a40 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63   If the commit c
37a50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
37a60 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68  non-zero then th
37a70 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20  e commit is.**  
37a80 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65          converte
37a90 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
37aa0 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31  k..**.** {H12961
37ab0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
37ac0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
37ad0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
37ae0 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
37af0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
37b00 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
37b10 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
37b20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
37b30 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
37b40 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
37b50 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20  lls back on the 
37b60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37b70 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
37b80 48 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c  H12962} The [sql
37b90 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
37ba0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
37bb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
37bc0 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   P.**          a
37bd0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
37be0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77   previous call w
37bf0 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  ith the same.** 
37c00 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
37c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37c20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65  , or NULL on the
37c30 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20   first call.**  
37c40 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61          for a pa
37c50 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
37c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
37c70 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45  **.** {H12963} E
37c80 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
37c90 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
37ca0 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73  ok()] overwrites
37cb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
37cc0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
37cd0 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61  ered by prior ca
37ce0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  lls..**.** {H129
37cf0 36 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67  64} If the F arg
37d00 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
37d10 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37d20 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
37d30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
37d40 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f   the rollback ho
37d50 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ok callback is c
37d60 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63  anceled and no c
37d70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
37d80 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77      is invoked w
37d90 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f  hen a transactio
37da0 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f  n rolls back..*/
37db0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63  .void *sqlite3_c
37dc0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74  ommit_hook(sqlit
37dd0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
37de0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64  *), void*);.void
37df0 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
37e00 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
37e10 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
37e20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
37e30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
37e40 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
37e50 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
37e60 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e  H12970} <S60400>
37e70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37e80 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
37e90 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
37ea0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
37eb0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  function.** with
37ec0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37ed0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74  onnection] ident
37ee0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
37ef0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
37f00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37f10 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
37f20 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
37f30 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
37f40 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
37f50 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
37f60 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
37f70 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tion.** for the 
37f80 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
37f90 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
37fa0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ridden..**.** Th
37fb0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37fc0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
37fd0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
37fe0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
37ff0 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
38000 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
38010 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66  eleted..** The f
38020 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
38030 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
38040 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
38050 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
38060 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
38070 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68  te_hook()..** Th
38080 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
38090 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
380a0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
380b0 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
380c0 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
380d0 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
380e0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
380f0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
38100 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
38110 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
38120 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  ed..** The third
38130 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
38140 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
38150 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
38160 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  inters to the.**
38170 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
38180 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e  ble name contain
38190 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64  ing the affected
381a0 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e   row..** The fin
381b0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
381c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77  meter is the row
381d0 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49  id of the row. I
381e0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 0a 2a 2a  n the case of.**
381f0 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
38200 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66   is the rowid af
38210 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74  ter the update t
38220 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
38230 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
38240 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
38250 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
38260 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
38270 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
38280 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
38290 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
382a0 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ence)..**.** If 
382b0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
382c0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
382d0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20  registered, its 
382e0 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73  pArg value.** is
382f0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
38300 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
38310 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  turned..**.** IN
38320 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
38330 7b 48 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71  {H12971} The [sq
38340 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
38350 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
38360 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
38370 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
38380 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74      function F t
38390 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
383a0 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  h first paramete
383b0 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  r P whenever.** 
383c0 20 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65           a table
383d0 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64   row is modified
383e0 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64  , inserted, or d
383f0 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  eleted on.**    
38400 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62        the [datab
38410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38420 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 33  D..**.** {H12973
38430 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
38440 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
38450 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
38460 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
38470 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 20  *          of P 
38480 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75 73  for the previous
38490 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d   call on the sam
384a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
384b0 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20  ection] D,.**   
384c0 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66         or NULL f
384d0 6f 72 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  or the first cal
384e0 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 35  l..**.** {H12975
384f0 7d 20 49 66 20 74 68 65 20 75 70 64 61 74 65 20  } If the update 
38500 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20  hook callback F 
38510 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  in [sqlite3_upda
38520 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a  te_hook(D,F,P)].
38530 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 4e  **          is N
38540 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20  ULL then the no 
38550 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73  update callbacks
38560 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a   are made..**.**
38570 20 7b 48 31 32 39 37 37 7d 20 45 61 63 68 20 63   {H12977} Each c
38580 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
38590 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
385a0 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72  P)] overrides pr
385b0 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20  ior calls.**    
385c0 20 20 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d        to the sam
385d0 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74  e interface on t
385e0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
385f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
38600 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 39 7d 20  .**.** {H12979} 
38610 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
38620 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
38630 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
38640 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20  ernal system.** 
38650 20 20 20 20 20 20 20 20 20 74 61 62 6c 65 73 20           tables 
38660 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d  such as sqlite_m
38670 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
38680 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f  _sequence are mo
38690 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  dified..**.** {H
386a0 31 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e  12981} The secon
386b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
386c0 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61  he update callba
386d0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
386e0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
386f0 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
38700 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51  E_DELETE] or [SQ
38710 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a  LITE_UPDATE],.**
38720 20 20 20 20 20 20 20 20 20 20 64 65 70 65 6e 64            depend
38730 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
38740 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
38750 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f   the callback to
38760 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   be invoked..**.
38770 2a 2a 20 7b 48 31 32 39 38 33 7d 20 54 68 65 20  ** {H12983} The 
38780 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
38790 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
387a0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
387b0 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20  in pointers.**  
387c0 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d          to zero-
387d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
387e0 20 73 74 72 69 6e 67 73 20 77 68 69 63 68 20 61   strings which a
387f0 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  re the names of 
38800 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
38810 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
38820 6c 65 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  le that is being
38830 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48   updated...** {H
38840 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c  12985} The final
38850 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
38860 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64  ter is the rowid
38870 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74 65   of the row afte
38880 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
38890 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e  e change occurs.
388a0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
388b0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
388c0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
388d0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
388e0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
388f0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
38900 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),