/ Hex Artifact Content
Login

Artifact 81dc1e8e50fb5c7cccf0a67a34cb796efc1d2a1e:


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 38 20 32 30 30 38 2f 30  n,v 1.398 2008/0
05f0: 39 2f 31 30 20 31 33 3a 30 39 3a 32 34 20 64 72  9/10 13:09:24 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: 20 26 26 20 28 5f 4d 53 43 5f 56 45 52 3e 31 32   && (_MSC_VER>12
0850: 30 30 29 20 0a 20 20 23 64 65 66 69 6e 65 20 53  00) .  #define S
0860: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0870: 20 5f 5f 64 65 63 6c 73 70 65 63 28 64 65 70 72   __declspec(depr
0880: 65 63 61 74 65 64 29 0a 23 65 6c 73 65 0a 20 20  ecated).#else.  
0890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
08a0: 45 50 52 45 43 41 54 45 44 0a 23 65 6e 64 69 66  EPRECATED.#endif
08b0: 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20  ../*.** Add the 
08c0: 61 62 69 6c 69 74 79 20 74 6f 20 6d 61 72 6b 20  ability to mark 
08d0: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 78  interfaces as ex
08e0: 70 65 72 69 6d 65 6e 74 61 6c 2e 0a 2a 2f 0a 23  perimental..*/.#
08f0: 69 66 20 28 5f 5f 47 4e 55 43 5f 5f 20 3e 20 34  if (__GNUC__ > 4
0900: 20 7c 7c 20 28 5f 5f 47 4e 55 43 5f 5f 20 3d 3d   || (__GNUC__ ==
0910: 20 34 20 26 26 20 5f 5f 47 4e 55 43 5f 4d 49 4e   4 && __GNUC_MIN
0920: 4f 52 5f 5f 20 3e 3d 20 33 29 29 0a 20 20 2f 2a  OR__ >= 3)).  /*
0930: 20 49 20 63 61 6e 20 63 6f 6e 66 69 72 6d 20 74   I can confirm t
0940: 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
0950: 77 6f 72 6b 20 6f 6e 20 76 65 72 73 69 6f 6e 20  work on version 
0960: 34 2e 31 2e 30 2e 2e 2e 20 2a 2f 0a 20 20 2f 2a  4.1.0... */.  /*
0970: 20 46 69 72 73 74 20 61 70 70 65 61 72 73 20 69   First appears i
0980: 6e 20 47 43 43 20 64 6f 63 73 20 66 6f 72 20 76  n GCC docs for v
0990: 65 72 73 69 6f 6e 20 34 2e 33 2e 30 20 2a 2f 0a  ersion 4.3.0 */.
09a0: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
09b0: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 5f 5f  _EXPERIMENTAL __
09c0: 61 74 74 72 69 62 75 74 65 5f 5f 20 28 28 77 61  attribute__ ((wa
09d0: 72 6e 69 6e 67 20 28 22 69 73 20 65 78 70 65 72  rning ("is exper
09e0: 69 6d 65 6e 74 61 6c 22 29 29 29 0a 23 65 6c 69  imental"))).#eli
09f0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
0a00: 45 52 29 20 26 26 20 28 5f 4d 53 43 5f 56 45 52  ER) && (_MSC_VER
0a10: 3e 31 32 30 30 29 20 0a 20 20 23 64 65 66 69 6e  >1200) .  #defin
0a20: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0a30: 45 4e 54 41 4c 20 5f 5f 64 65 63 6c 73 70 65 63  ENTAL __declspec
0a40: 28 64 65 70 72 65 63 61 74 65 64 28 22 77 61 73  (deprecated("was
0a50: 20 64 65 63 6c 61 72 65 64 20 65 78 70 65 72 69   declared experi
0a60: 6d 65 6e 74 61 6c 22 29 29 0a 23 65 6c 73 65 0a  mental")).#else.
0a70: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
0a80: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 23 65  _EXPERIMENTAL.#e
0a90: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  ndif../*.** Ensu
0aa0: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
0ab0: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
0ac0: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
0ad0: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
0ae0: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
0af0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
0b00: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
0b10: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
0b20: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0b30: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
0b40: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0b50: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0b60: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0b70: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0b80: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0b90: 48 31 30 30 31 30 7d 20 3c 53 36 30 31 30 30 3e  H10010} <S60100>
0ba0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
0bb0: 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51  E_VERSION and SQ
0bc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0bd0: 42 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a  BER #defines in.
0be0: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  ** the sqlite3.h
0bf0: 20 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68   file specify th
0c00: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  e version of SQL
0c10: 69 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a  ite with which.*
0c20: 2a 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69  * that header fi
0c30: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  le is associated
0c40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72  ..**.** The "ver
0c50: 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20  sion" of SQLite 
0c60: 69 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74  is a string of t
0c70: 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e  he form "X.Y.Z".
0c80: 0a 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22  .** The phrase "
0c90: 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22  alpha" or "beta"
0ca0: 20 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64   might be append
0cb0: 65 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a  ed after the Z..
0cc0: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69  ** The X value i
0cd0: 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20  s major version 
0ce0: 6e 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20  number always 3 
0cf0: 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54  in SQLite3..** T
0d00: 68 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20  he X value only 
0d10: 63 68 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63  changes when bac
0d20: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
0d30: 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65  lity is.** broke
0d40: 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20  n and we intend 
0d50: 74 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62  to never break b
0d60: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
0d70: 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59  bility..** The Y
0d80: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69   value is the mi
0d90: 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  nor version numb
0da0: 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e  er and only chan
0db0: 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72  ges when.** ther
0dc0: 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74  e are major feat
0dd0: 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73  ure enhancements
0de0: 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72   that are forwar
0df0: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a  ds compatible.**
0e00: 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72   but not backwar
0e10: 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a  ds compatible..*
0e20: 2a 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73  * The Z value is
0e30: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d   the release num
0e40: 62 65 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65  ber and is incre
0e50: 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65  mented with.** e
0e60: 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20  ach release but 
0e70: 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30  resets back to 0
0e80: 20 77 68 65 6e 65 76 65 72 20 59 20 69 73 20 69   whenever Y is i
0e90: 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a  ncremented..**.*
0ea0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0eb0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0ec0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
0ed0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0ee0: 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  r()]..**.** INVA
0ef0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
0f00: 31 30 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54  10011} The SQLIT
0f10: 45 5f 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e  E_VERSION #defin
0f20: 65 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  e in the sqlite3
0f30: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 20 73  .h header file s
0f40: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
0f50: 20 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73   evaluate to a s
0f60: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0f70: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0f80: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0f90: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0fa0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0fb0: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0fc0: 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d 20 54 68  *.** {H10014} Th
0fd0: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0fe0: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0ff0: 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f  shall resolve to
1000: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
1010: 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
1020: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
1030: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
1040: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
1050: 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  Z.**          ar
1060: 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  e the major vers
1070: 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69  ion, minor versi
1080: 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20  on, and release 
1090: 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69  number..*/.#defi
10a0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
10b0: 4e 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  N         "--VER
10c0: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
10d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
10e0: 45 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55  ER  --VERSION-NU
10f0: 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41  MBER--../*.** CA
1100: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1110: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1120: 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 32 30   Numbers {H10020
1130: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45  } <S60100>.** KE
1140: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
1150: 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  version.**.** Th
1160: 65 73 65 20 66 65 61 74 75 72 65 73 20 70 72 6f  ese features pro
1170: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
1180: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
1190: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
11a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
11b0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
11c0: 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65   #defines in the
11d0: 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 72 65   header, but are
11e0: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
11f0: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  ith the library 
1200: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68  instead of the h
1210: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75  eader file.  Cau
1220: 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65 72  tious programmer
1230: 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75  s might.** inclu
1240: 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74 68  de a check in th
1250: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
1260: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a 2a  to verify that.*
1270: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1280: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c  sion_number() al
1290: 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
12a0: 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54   value.** [SQLIT
12b0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ]..**.** The sql
12d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
12e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
12f0: 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  ns the same info
1300: 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a  rmation as is.**
1310: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
1320: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1330: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1340: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1350: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20  ided.** for use 
1360: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c  in DLLs since DL
1370: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20  L users usually 
1380: 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72 65  do not have dire
1390: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
13a0: 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73  ing.** constants
13b0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
13c0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
13d0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31  S:.**.** {H10021
13e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1400: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
1410: 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  all return.**   
1420: 20 20 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65         an intege
1430: 72 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49  r equal to [SQLI
1440: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1450: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  R]..**.** {H1002
1460: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1470: 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20  version] string 
1480: 63 6f 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63  constant shall c
1490: 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ontain.**       
14a0: 20 20 20 74 68 65 20 74 65 78 74 20 6f 66 20 74     the text of t
14b0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
14c0: 4f 4e 5d 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ON] string..**.*
14d0: 2a 20 7b 48 31 30 30 32 33 7d 20 54 68 65 20 5b  * {H10023} The [
14e0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14f0: 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  on()] function s
1500: 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  hall return.**  
1510: 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
1520: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1530: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e  3_version] strin
1540: 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53  g constant..*/.S
1550: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e  QLITE_EXTERN con
1560: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
1570: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74  version[];.const
1580: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
1590: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
15a0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62  .int sqlite3_lib
15b0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
15c0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
15d0: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
15e0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
15f0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20  y Is Threadsafe 
1600: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30  {H10100} <S60100
1610: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
1620: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
1630: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
1640: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1650: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1660: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1670: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 31 20  ocessor macro 1 
1680: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
1690: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
16a0: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
16b0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
16c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
16d0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
16e0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
16f0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
1700: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
1710: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
1720: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
1730: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
1740: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
1750: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
1760: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
1770: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
1780: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
1790: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
17a0: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
17b0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
17c0: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
17d0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
17e0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
17f0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
1800: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
1810: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
1820: 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  led..** The defa
1830: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ult behavior is 
1840: 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62  for mutexes to b
1850: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  e enabled..**.**
1860: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1870: 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61  can be used by a
1880: 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65   program to make
1890: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
18a0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
18b0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
18c0: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
18d0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
18e0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
18f0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1900: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1910: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
1920: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
1930: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
1940: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
1950: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
1960: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
1970: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
1980: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
1990: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
19a0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
19b0: 46 45 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65  FE=1 then mutexe
19c0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
19d0: 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20   default but.** 
19e0: 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20  can be fully or 
19f0: 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c  partially disabl
1a00: 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20  ed using a call 
1a10: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
1a20: 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68  ig()].** with th
1a30: 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f  e verbs [SQLITE_
1a40: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
1a50: 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EAD], [SQLITE_CO
1a60: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1a70: 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
1a80: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20  _CONFIG_MUTEX]. 
1a90: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
1aa0: 65 20 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69  e of this functi
1ab0: 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79  on shows.** only
1ac0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d   the default com
1ad0: 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e  pile-time settin
1ae0: 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  g, not any run-t
1af0: 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74  ime changes.** t
1b00: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a  o that setting..
1b10: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
1b20: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
1b30: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
1b40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
1b50: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  rmation..**.** I
1b60: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1b70: 20 7b 48 31 30 31 30 31 7d 20 54 68 65 20 5b 73   {H10101} The [s
1b80: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1b90: 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  e()] function sh
1ba0: 61 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65  all return nonze
1bb0: 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  ro if.**        
1bc0: 20 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a    and only if.**
1bd0: 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
1be0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1bf0: 74 68 20 74 68 65 20 69 74 73 20 6d 75 74 65 78  th the its mutex
1c00: 65 73 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  es enabled by de
1c10: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
1c20: 30 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20  0102} The value 
1c30: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
1c40: 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1c50: 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a  afe()] function.
1c60: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
1c70: 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 65  l not change whe
1c80: 6e 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 20  n mutex setting 
1c90: 61 72 65 20 6d 6f 64 69 66 69 65 64 20 61 74 0a  are modified at.
1ca0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 74  **          runt
1cb0: 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ime using the [s
1cc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1cd0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 0a   interface and .
1ce0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 73 70 65  **          espe
1cf0: 63 69 61 6c 6c 79 20 74 68 65 20 5b 53 51 4c 49  cially the [SQLI
1d00: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1d10: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 20 20 20 20  THREAD],.**     
1d20: 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e       [SQLITE_CON
1d30: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1d40: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
1d50: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a  _SERIALIZED],.**
1d60: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 53            and [S
1d70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
1d80: 45 58 5d 20 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e  EX] verbs..*/.in
1d90: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
1da0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
1db0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
1dc0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1dd0: 20 48 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d   Handle {H12000}
1de0: 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S40200>.** KEY
1df0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
1e00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
1e10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e20: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
1e30: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
1e40: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
1e50: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
1e60: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
1e70: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
1e80: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
1e90: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
1ea0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
1eb0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
1ec0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
1ed0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
1ee0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1ef0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1f00: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1f10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1f20: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
1f30: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
1f40: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
1f50: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
1f60: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
1f70: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
1f80: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
1f90: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
1fa0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1fb0: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1fc0: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
1fd0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
1fe0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
1ff0: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2000: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
2010: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
2020: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
2030: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2040: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
2050: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
2060: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2070: 70 65 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31  pes {H10200} <S1
2080: 30 31 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0110>.** KEYWORD
2090: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
20a0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
20b0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
20c0: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
20d0: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
20e0: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
20f0: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2100: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2110: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2120: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2130: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2140: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2150: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2160: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
2170: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
2180: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
2190: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
21a0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
21b0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
21c0: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
21d0: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
21e0: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
21f0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2200: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54  **.** {H10201} T
2210: 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34  he [sqlite_int64
2220: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69  ] and [sqlite3_i
2230: 6e 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c  nt64] type shall
2240: 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20   specify.**     
2250: 20 20 20 20 20 61 20 36 34 2d 62 69 74 20 73 69       a 64-bit si
2260: 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
2270: 0a 2a 2a 20 7b 48 31 30 32 30 32 7d 20 54 68 65  .** {H10202} The
2280: 20 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d   [sqlite_uint64]
2290: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69   and [sqlite3_ui
22a0: 6e 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c  nt64] type shall
22b0: 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20   specify.**     
22c0: 20 20 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e       a 64-bit un
22d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
22e0: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
22f0: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79  _INT64_TYPE.  ty
2300: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  pedef SQLITE_INT
2310: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69  64_TYPE sqlite_i
2320: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2330: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2340: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2350: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20  e_uint64;.#elif 
2360: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52  defined(_MSC_VER
2370: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42  ) || defined(__B
2380: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70  ORLANDC__).  typ
2390: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c  edef __int64 sql
23a0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
23b0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f  edef unsigned __
23c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
23d0: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70  t64;.#else.  typ
23e0: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  edef long long i
23f0: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  nt sqlite_int64;
2400: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2410: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  ned long long in
2420: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  t sqlite_uint64;
2430: 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20  .#endif.typedef 
2440: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2450: 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65  ite3_int64;.type
2460: 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  def sqlite_uint6
2470: 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4 sqlite3_uint64
2480: 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70  ;../*.** If comp
2490: 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63  iling for a proc
24a0: 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73  essor that lacks
24b0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24c0: 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73  support,.** subs
24d0: 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66  titute integer f
24e0: 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e  or floating-poin
24f0: 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  t..*/.#ifdef SQL
2500: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
2510: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
2520: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2530: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
2540: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
2550: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
2560: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32   Connection {H12
2570: 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c 53 34  010} <S30100><S4
2580: 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0200>.**.** This
2590: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
25a0: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
25b0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
25c0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ect..**.** Appli
25d0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
25e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25f0: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2600: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2610: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2620: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2630: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2640: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
2650: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
2660: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2670: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2680: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2690: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  se the object..*
26a0: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  * The [sqlite3_n
26b0: 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65  ext_stmt()] inte
26c0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26d0: 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a  d to locate all.
26e0: 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
26f0: 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61  tements] associa
2700: 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
2710: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2720: 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20   if desired..** 
2730: 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67  Typical code mig
2740: 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69  ht look like thi
2750: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2760: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71  uote><pre>.** sq
2770: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2780: 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53  t;.** while( (pS
2790: 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65  tmt = sqlite3_ne
27a0: 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21  xt_stmt(db, 0))!
27b0: 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20  =0 ){.** &nbsp; 
27c0: 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69    sqlite3_finali
27d0: 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a  ze(pStmt);.** }.
27e0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
27f0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  quote>.**.** If 
2800: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2810: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69  ] is invoked whi
2820: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
2830: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
2840: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2850: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2860: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
2870: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2880: 2a 2a 20 7b 48 31 32 30 31 31 7d 20 41 20 73 75  ** {H12011} A su
2890: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
28a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
28b0: 43 29 5d 20 73 68 61 6c 6c 20 64 65 73 74 72 6f  C)] shall destro
28c0: 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
28d0: 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
28e0: 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43  ection] object C
28f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d  ..**.** {H12012}
2900: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
2910: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2920: 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72  lose(C)] shall r
2930: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e  eturn SQLITE_OK.
2940: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20  .**.** {H12013} 
2950: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2960: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2970: 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65  ose(C)] shall re
2980: 6c 65 61 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20  lease all.**    
2990: 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
29a0: 20 73 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65   system resource
29b0: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
29c0: 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
29d0: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20  ection].**      
29e0: 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31      C..**.** {H1
29f0: 32 30 31 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20  2014} A call to 
2a00: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2a10: 29 5d 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  )] on a [databas
2a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20  e connection] C 
2a30: 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
2a40: 20 68 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65   has one or more
2a50: 20 6f 70 65 6e 20 5b 70 72 65 70 61 72 65 64 20   open [prepared 
2a60: 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c  statements] shal
2a70: 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20  l fail with.**  
2a80: 20 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49          an [SQLI
2a90: 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 63  TE_BUSY] error c
2aa0: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30  ode..**.** {H120
2ab0: 31 35 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  15} A call to [s
2ac0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
2ad0: 20 77 68 65 72 65 20 43 20 69 73 20 61 20 4e 55   where C is a NU
2ae0: 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c  LL pointer shall
2af0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2b00: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  urn SQLITE_OK..*
2b10: 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57 68  *.** {H12019} Wh
2b20: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  en [sqlite3_clos
2b30: 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  e(C)] is invoked
2b40: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a  connection] C.**
2b60: 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 68            that h
2b70: 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72 61  as a pending tra
2b80: 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74 72  nsaction, the tr
2b90: 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c 20  ansaction shall 
2ba0: 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  be.**          r
2bb0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
2bc0: 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
2bd0: 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54 68  *.** {A12016} Th
2be0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2bf0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2c00: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2c10: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  er a NULL.**    
2c20: 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f 72        pointer or
2c30: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
2c40: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
2c50: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
2c60: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
2c70: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2c80: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
2c90: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ca0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
2cb0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
2cc0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69  sly closed..*/.i
2cd0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2ce0: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2cf0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2d00: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2d10: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2d20: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2d30: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2d40: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
2d50: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
2d60: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
2d70: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
2d80: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
2d90: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2da0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2db0: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2dc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2dd0: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2de0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2df0: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2e00: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2e10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2e20: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2e30: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
2e40: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
2e50: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2e60: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
2e70: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
2e80: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
2e90: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2ea0: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2eb0: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2ec0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2ed0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2ee0: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2ef0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2f00: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2f10: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2f20: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2f30: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
2f40: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
2f50: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
2f60: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
2f70: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
2f80: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
2f90: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2fa0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2fb0: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2fc0: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2fd0: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2fe0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2ff0: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
3000: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
3010: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
3020: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
3030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
3040: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
3050: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3060: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
3070: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
3080: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
3090: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
30a0: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
30b0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
30c0: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
30d0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
30e0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
30f0: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
3100: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
3110: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3120: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3130: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
3140: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
3150: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3160: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
3170: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
3180: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3190: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
31a0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
31b0: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
31c0: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
31d0: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
31e0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
31f0: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
3200: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3210: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
3220: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3230: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
3240: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3250: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
3260: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
3270: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3280: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3290: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
32a0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32b0: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
32c0: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
32d0: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
32e0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
32f0: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
3300: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
3310: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3320: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3330: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3340: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
3350: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
3360: 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41 20  *.** {H12101} A 
3370: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
3380: 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
3390: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
33a0: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
33b0: 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c 6c  hall sequentiall
33c0: 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f  y evaluate all o
33d0: 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  f the UTF-8 enco
33e0: 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ded,.**         
33f0: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
3400: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
3410: 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
3420: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
3430: 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53 20         string S 
3440: 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 65  within the conte
3450: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  xt of the [datab
3460: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3470: 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 32  D..**.** {H12102
3480: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3490: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
34a0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
34b0: 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a  ] is NULL then.*
34c0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
34d0: 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e  ctions of the in
34e0: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65  terface shall be
34f0: 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20   the same as if 
3500: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
3510: 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 65  S parameter were
3520: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3530: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34 7d  ..**.** {H12104}
3540: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3550: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3560: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b  ec()] shall be [
3570: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c  SQLITE_OK] if al
3580: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  l.**          SQ
3590: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e  L statements run
35a0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e   successfully an
35b0: 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  d to completion.
35c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d 20  .**.** {H12105} 
35d0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
35e0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
35f0: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e  c()] shall be an
3600: 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
3610: 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72           non-zer
3620: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
3630: 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d  f any SQL statem
3640: 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ent fails..**.**
3650: 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e 65   {H12107} If one
3660: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
3670: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68  SQL statements h
3680: 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  anded to [sqlite
3690: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
36a0: 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 73        return res
36b0: 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 64  ults and the 3rd
36c0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
36d0: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20  t NULL, then.** 
36e0: 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
36f0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
3700: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
3710: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68  3rd parameter sh
3720: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
3730: 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20     invoked once 
3740: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
3750: 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  result..**.** {H
3760: 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 61  12110} If the ca
3770: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
3780: 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20   non-zero value 
3790: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78  then [sqlite3_ex
37a0: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ec()].**        
37b0: 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 68    shall abort th
37c0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
37d0: 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  it is currently 
37e0: 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20  evaluating,.**  
37f0: 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c          skip all
3800: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3810: 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
3820: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41  return [SQLITE_A
3830: 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  BORT]..**.** {H1
3840: 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2113} The [sqlit
3850: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69  e3_exec()] routi
3860: 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 74  ne shall pass it
3870: 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 4th parameter 
3880: 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20  through.**      
3890: 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70      as the 1st p
38a0: 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
38b0: 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
38c0: 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71  {H12116} The [sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
38e0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
38f0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3900: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
3910: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
3920: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
3930: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3940: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
3950: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
3960: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31  lt..**.** {H1211
3970: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
3980: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3990: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33 72  shall set the 3r
39a0: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
39b0: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ts.**          c
39c0: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e  allback to be an
39d0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
39e0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f  rs to strings ho
39f0: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  lding the.**    
3a00: 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f 72        values for
3a10: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20   each column in 
3a20: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
3a30: 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a  lt set row as.**
3a40: 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
3a50: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
3a60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
3a70: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d 20  .**.** {H12122} 
3a80: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3a90: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3aa0: 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20 70  ll set the 4th p
3ab0: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
3ac0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
3ad0: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72  back to be an ar
3ae0: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3af0: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69  to strings holdi
3b00: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
3b10: 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75     names of resu
3b20: 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62  lt columns as ob
3b30: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
3b40: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3b50: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3b60: 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70  25} If the 3rd p
3b70: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3b90: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3ba0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3bb0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c  xec()] shall sil
3bc0: 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71 75  ently discard qu
3bd0: 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a  ery results..**.
3be0: 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20 61  ** {H12131} If a
3bf0: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
3c00: 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20  hile parsing or 
3c10: 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f  evaluating any o
3c20: 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20  f the SQL.**    
3c30: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
3c40: 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65   in the S parame
3c50: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
3c60: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3c70: 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20   and if.**      
3c80: 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65      the E parame
3c90: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
3ca0: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3cb0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f  xec()] shall sto
3cc0: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  re.**          i
3cd0: 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69  n *E an appropri
3ce0: 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
3cf0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
3d00: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
3d10: 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
3d20: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3d30: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d40: 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
3d50: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3d60: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73   routine shall s
3d70: 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  et the value of.
3d80: 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74  **          *E t
3d90: 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e  o NULL if E is n
3da0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72  ot NULL and ther
3db0: 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e  e are no errors.
3dc0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d 20  .**.** {H12137} 
3dd0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3de0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75  c(D,S,C,A,E)] fu
3df0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74  nction shall set
3e00: 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65   the [error code
3e10: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
3e20: 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73  d message access
3e30: 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65  ible via [sqlite
3e40: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3e50: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3e60: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3e70: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3e80: 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g16()]..**.** {H
3e90: 31 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20  12138} If the S 
3ea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3eb0: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
3ec0: 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f  ,A,E)] is NULL o
3ed0: 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
3ee0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
3ef0: 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e   contains nothin
3f00: 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
3f10: 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74  tespace, comment
3f20: 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s,.**          a
3f30: 6e 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73  nd/or semicolons
3f40: 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f  , then results o
3f50: 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  f [sqlite3_errco
3f60: 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  de()],.**       
3f70: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d     [sqlite3_errm
3f80: 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  sg()], and [sqli
3f90: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a  te3_errmsg16()].
3fa0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
3fb0: 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63  l reset to indic
3fc0: 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a  ate no errors..*
3fd0: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
3fe0: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d  :.**.** {A12141}
3ff0: 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
4000: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
4010: 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65  _exec()] must be
4020: 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70   an valid and op
4030: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
4040: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4050: 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ion]..**.** {A12
4060: 31 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73  142} The databas
4070: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
4080: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
4090: 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  while.**        
40a0: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28    [sqlite3_exec(
40b0: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  )] is running..*
40c0: 2a 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 68  *.** {A12143} Th
40d0: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
40e0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73  on should use [s
40f0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74  qlite3_free()] t
4100: 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20  o free.**       
4110: 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68     the memory th
4120: 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65  at *errmsg is le
4130: 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f  ft pointing at o
4140: 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  nce the error.**
4150: 20 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67            messag
4160: 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  e is no longer n
4170: 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  eeded..**.** {A1
4180: 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74  2145} The SQL st
4190: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20  atement text in 
41a0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
41b0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
41c0: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ec()].**        
41d0: 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e    must remain un
41e0: 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73  changed while [s
41f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
4200: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
4210: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
4220: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4240: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4250: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
4260: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
4270: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
4280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4290: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
42a0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
42b0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
42c0: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
42d0: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
42e0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
42f0: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4320: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
4330: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
4340: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
4350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4360: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
4370: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
4380: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
4390: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
43a0: 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20   Codes {H10210} 
43b0: 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
43c0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
43d0: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
43e0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
43f0: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
4400: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
4410: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
4420: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
4430: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
4440: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4450: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4460: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4470: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20  er to indicates 
4480: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
4490: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
44a0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
44b0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
44c0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
44d0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
44e0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
44f0: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
4500: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4510: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4520: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
4530: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
4540: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
4550: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
4560: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
4570: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
4580: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
4590: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
45a0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
45b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
45c0: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
45d0: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
45e0: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
45f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4600: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
4610: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
4620: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
4630: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4640: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
4650: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
4660: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
4670: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
4680: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
4690: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
46a0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
46b0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
46c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
46d0: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
46e0: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
46f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
4700: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4710: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
4720: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
4730: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
4740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
4750: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
4760: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
4770: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
4780: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4790: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
47a0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
47b0: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
47c0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
47d0: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
47e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
47f0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
4800: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
4810: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
4820: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4830: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
4840: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
4850: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
4860: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
4890: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61   /* NOT USED. Ta
48a0: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f  ble or record no
48b0: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69  t found */.#defi
48c0: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
48d0: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
48e0: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
48f0: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4900: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4910: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4920: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4930: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4940: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4950: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4960: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
4970: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44    /* NOT USED. D
4980: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4990: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
49b0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
49c0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
49d0: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
49e0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
49f0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a00: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a10: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4a20: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4a30: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4a40: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4a50: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a70: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4a80: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4a90: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4aa0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4ab0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4ac0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4ad0: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4ae0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4af0: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b00: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b10: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4b40: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4b50: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4b60: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4b70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4b80: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4b90: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4ba0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4bb0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4bc0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4bd0: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4be0: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4c00: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4c10: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4c20: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4c30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4c50: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4c60: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4c70: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4c80: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4ca0: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4cb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4cc0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cd0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4ce0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cf0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4d00: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4d10: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d20: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d30: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d50: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d60: 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53  odes {H10220} <S
4d70: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10700>.** KEYWOR
4d80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
4d90: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
4da0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
4db0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4dc0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4dd0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72  ode} {extended r
4de0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
4df0: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4e00: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4e10: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4e20: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4e30: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
4e40: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
4e50: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4e60: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4e70: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4e80: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
4e90: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
4ea0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
4eb0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
4ec0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
4ed0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
4ee0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4ef0: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4f00: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4f10: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4f20: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4f30: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4f40: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4f50: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4f60: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4f70: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4f80: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
4f90: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
4fa0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
4fb0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
4fc0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74   errors. The ext
4fd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4fe0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  es are enabled o
4ff0: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
5000: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
5010: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
5020: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
5030: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5040: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
5050: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  API..**.** Some 
5060: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
5070: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
5080: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
5090: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
50a0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
50b0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
50d0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
50e0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
50f0: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
5100: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
5110: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
5120: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
5130: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
5140: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
5150: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
5160: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
5170: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
5180: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
5190: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
51a0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
51b0: 79 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y zero..**.** IN
51c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
51d0: 7b 48 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d  {H10223} The sym
51e0: 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61  bolic name for a
51f0: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
5200: 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e  t code shall con
5210: 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
5220: 20 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d    a related prim
5230: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
5240: 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a  as a prefix..**.
5250: 2a 2a 20 7b 48 31 30 32 32 34 7d 20 50 72 69 6d  ** {H10224} Prim
5260: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
5270: 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74  names shall cont
5280: 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22  ain a single "_"
5290: 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a   character..**.*
52a0: 2a 20 7b 48 31 30 32 32 35 7d 20 45 78 74 65 6e  * {H10225} Exten
52b0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
52c0: 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74  names shall cont
52d0: 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  ain two or more 
52e0: 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "_" characters..
52f0: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 54  **.** {H10226} T
5300: 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65  he numeric value
5310: 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20   of an extended 
5320: 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c  result code shal
5330: 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a 2a  l contain the.**
5340: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69            numeri
5350: 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63  c value of its c
5360: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69  orresponding pri
5370: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
5380: 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
5390: 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66  its least signif
53a0: 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f  icant 8 bits..*/
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53c0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
53d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53e0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
53f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5400: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5410: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5420: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5440: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5450: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5460: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5480: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
5490: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54a0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
54b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
54c0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
54d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
54e0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
54f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5500: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5510: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5520: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5570: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
5580: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
5590: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55a0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
55c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55e0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5600: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5640: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
5670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
5680: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
5690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56a0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
56b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
56c0: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
56d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56e0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
56f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5700: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5710: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5720: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5740: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5750: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5760: 31 35 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  15<<8))../*.** C
5770: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5780: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5790: 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d  rations {H10230}
57a0: 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37 30   <H11120> <H1270
57b0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  0>.**.** These b
57c0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
57d0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
57e0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
57f0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5800: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5810: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5820: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5830: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78  rameter to the x
5840: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74  Open method of t
5850: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
5860: 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  fs] object..*/.#
5870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5880: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
5890: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
58b0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
58c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
58d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
58e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
58f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
5900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5910: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
5920: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5930: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5940: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5950: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5970: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
5980: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
59a0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
59b0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
59c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
59d0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
59e0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
59f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5a00: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
5a10: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23      0x00000800.#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5a30: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
5a40: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
5a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5a60: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
5a70: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
5a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5a90: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
5aa0: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 23  L   0x00004000.#
5ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5ac0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
5ad0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0a 23      0x00008000.#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5af0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
5b00: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0a 0a      0x00010000..
5b10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5b20: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
5b30: 69 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d 20  istics {H10240} 
5b40: 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H11120>.**.** T
5b50: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5b60: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
5b70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5b80: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
5b90: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
5ba0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
5bb0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
5bc0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
5bd0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
5be0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
5bf0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
5c00: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5c10: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5c20: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5c30: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c40: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5c50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5c60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5c70: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5c80: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
5c90: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5ca0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5cc0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
5cd0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5ce0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5cf0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5d00: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5d10: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5d20: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5d30: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5d40: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5d50: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5d60: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5d70: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
5d80: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
5d90: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5da0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
5db0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5dc0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
5dd0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5de0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5df0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5e00: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5e10: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5e20: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5e30: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5e40: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5e50: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5e60: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5e70: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
5e80: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
5eb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5ec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ed0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
5ee0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5ef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5f10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5f40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5f70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5f80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fc0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5fd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5fe0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ff0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
6000: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6020: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
6030: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6050: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6060: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
6070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6080: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6090: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
60a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
60b0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
60c0: 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c  evels {H10250} <
60d0: 48 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30 3e  H11120> <H11310>
60e0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
60f0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
6100: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6110: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
6120: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
6130: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
6140: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
6150: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
6160: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
6170: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6180: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
6190: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
61a0: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
61c0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
61f0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6200: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6210: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6220: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6230: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
6240: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
6250: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
6260: 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30  pe Flags {H10260
6270: 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a  } <H11120>.**.**
6280: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6290: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
62a0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
62b0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
62c0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
62d0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
62e0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
62f0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6300: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6310: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6320: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6330: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6340: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6350: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6360: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6370: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6380: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6390: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
63a0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
63b0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
63c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
63d0: 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61  _NORMAL flag mea
63e0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72  ns.** to use nor
63f0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6400: 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54  ntics. The SQLIT
6410: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6420: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6430: 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20   Mac OS-X style 
6440: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6450: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6470: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6480: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6490: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
64a0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
64b0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
64c0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
64d0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
64e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
64f0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
6500: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31   File Handle {H1
6510: 31 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1110} <S20110>.*
6520: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
6530: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
6540: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
6550: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a   file in the OS.
6560: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  ** interface lay
6570: 65 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  er.  Individual 
6580: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70  OS interface imp
6590: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
65a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
65b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
65c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
65d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
65e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
65f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
6600: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
6610: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
6620: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6630: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
6640: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
6650: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
6660: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
6670: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
6680: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
6690: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
66a0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
66b0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
66c0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
66d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
66e0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
66f0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
6700: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
6710: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
6720: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6730: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
6740: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
6750: 74 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31  t {H11120} <S201
6760: 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  10>.**.** Every 
6770: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6780: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6790: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
67a0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
67b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
67c0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
67d0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
67e0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
67f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6800: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
6810: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6820: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6830: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6840: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6850: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6860: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6870: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6880: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6890: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
68a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
68b0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
68c0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
68d0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
68e0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
68f0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
6900: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
6910: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
6920: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
6930: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
6940: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
6950: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
6960: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
6970: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
6980: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6990: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
69a0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
69b0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
69c0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
69d0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
69e0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
69f0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
6a00: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
6a10: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
6a20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
6a30: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
6a40: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6a50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
6a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a70: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
6a80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6a90: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
6aa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6ab0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
6ac0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6ad0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
6ae0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
6af0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
6b00: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
6b10: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
6b20: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
6b30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
6b40: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
6b50: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
6b60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
6b70: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
6b80: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
6b90: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
6ba0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
6bb0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
6bc0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
6bd0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
6be0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
6bf0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
6c00: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
6c10: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
6c20: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
6c30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
6c40: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
6c50: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
6c60: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
6c70: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
6c80: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
6c90: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
6ca0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
6cb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6cc0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
6cd0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
6ce0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
6cf0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
6d00: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
6d10: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
6d20: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
6d30: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
6d40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
6d50: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
6d60: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
6d70: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
6d80: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
6d90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
6da0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
6db0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
6dc0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
6dd0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
6de0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
6df0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
6e00: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
6e10: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
6e20: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
6e30: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
6e40: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
6e50: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
6e60: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
6e70: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
6e80: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
6e90: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
6ea0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
6eb0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
6ec0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
6ed0: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  e..** A [SQLITE_
6ee0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6ef0: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
6f00: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
6f10: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
6f20: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
6f30: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
6f40: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
6f50: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
6f60: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
6f70: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
6f80: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
6f90: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  s..**.** The xSe
6fa0: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
6fb0: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
6fc0: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
6fd0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6fe0: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
6ff0: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
7000: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
7010: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
7020: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
7030: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
7040: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
7050: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
7060: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
7070: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
7080: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
7090: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
70a0: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
70b0: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
70c0: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
70d0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
7100: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7110: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
7120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7130: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
7140: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7150: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
7160: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7170: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
7180: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7190: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
71a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
71b0: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
71c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
71d0: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
71e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
71f0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
7200: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7210: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
7220: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7230: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
7240: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
7250: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
7260: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
7270: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
7280: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
7290: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
72a0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
72b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
72c0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
72d0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
72e0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
72f0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
7300: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
7310: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
7320: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
7330: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
7340: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
7350: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
7360: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7370: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
7380: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
7390: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
73a0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
73b0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
73c0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
73d0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
73e0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
73f0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
7400: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
7410: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7420: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
7430: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
7440: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
7450: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
7460: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
7470: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
7480: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65  Write()..*/.type
7490: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
74a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
74b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
74c0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
74d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
74e0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
74f0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7500: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7510: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7520: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7530: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7540: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7550: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
7560: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7570: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
7580: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
7590: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
75a0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
75b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
75c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
75d0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
75e0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
75f0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
7600: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
7610: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7620: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7630: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
7640: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
7650: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
7660: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
7670: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
7690: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
76a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
76b0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
76c0: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
76d0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
76e0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
76f0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
7700: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
7710: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7720: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
7730: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
7740: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
7750: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7760: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7770: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7780: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7790: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
77a0: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
77b0: 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30   Opcodes {H11310
77c0: 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a  } <S30800>.**.**
77d0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
77e0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
77f0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7800: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7810: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7820: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7830: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7840: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7850: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7860: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7870: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
7880: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
7890: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
78a0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
78b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
78c0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
78d0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
78e0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
78f0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
7900: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
7910: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
7920: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7930: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
7940: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
7950: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7960: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
7970: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7980: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
7990: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
79a0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
79b0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
79c0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
79d0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
79e0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
79f0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
7a00: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
7a10: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
7a20: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
7a30: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
7a40: 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a  ATE        1../*
7a50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
7a60: 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31  tex Handle {H171
7a70: 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a  10} <S20130>.**.
7a80: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
7a90: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
7aa0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
7ab0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
7ac0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
7ad0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
7ae0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
7af0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
7b00: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
7b10: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
7b20: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
7b30: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
7b40: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
7b50: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
7b60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
7b70: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
7b80: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
7b90: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
7ba0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
7bb0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
7bc0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7bd0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
7be0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
7bf0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7c00: 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34  ce Object {H1114
7c10: 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S20100>.**.*
7c20: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
7c30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7c40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7c50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
7c60: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
7c70: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
7c80: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
7c90: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
7ca0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
7cb0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
7cc0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
7cd0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
7ce0: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
7cf0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
7d00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
7d10: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
7d20: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
7d30: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
7d40: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
7d50: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
7d60: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
7d70: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
7d80: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
7d90: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
7da0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
7db0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
7dc0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
7dd0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7de0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
7df0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
7e00: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
7e10: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
7e20: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
7e30: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
7e40: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
7e50: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
7e60: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
7e70: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
7e80: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
7e90: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
7ea0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
7eb0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
7ec0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
7ed0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
7ee0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
7ef0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
7f00: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
7f10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
7f20: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
7f30: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
7f40: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
7f50: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
7f60: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
7f70: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
7f80: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
7f90: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
7fa0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
7fb0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
7fc0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
7fd0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
7fe0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
7ff0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
8000: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
8010: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
8020: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
8030: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
8040: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
8050: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
8060: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
8070: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
8080: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
8090: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
80a0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
80b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
80c0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
80d0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
80e0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
80f0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
8100: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
8110: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
8120: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
8130: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
8140: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
8150: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
8160: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
8170: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
8180: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
8190: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
81a0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
81b0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
81c0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
81d0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
81e0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
81f0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
8200: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  les..**.** {H111
8210: 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  41} SQLite will 
8220: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
8230: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8240: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
8250: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
8260: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
8270: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
8280: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
8290: 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20  name().  SQLite 
82a0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
82b0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
82c0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
82d0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
82e0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
82f0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b   is.** called. {
8300: 45 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66  END}  Because of
8310: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
8320: 6e 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntense,.** the [
8330: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
8340: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
8350: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
8360: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
8370: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
8380: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
8390: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
83a0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
83b0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
83c0: 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  is xOpen is a NU
83d0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
83e0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
83f0: 76 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d  vite its own tem
8400: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
8410: 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65  the file.  Whene
8420: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
8430: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8440: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
8450: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
8460: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
8470: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
8480: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
8490: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
84a0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  LOSE]..**.** {H1
84b0: 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20  1142} The flags 
84c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
84d0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
84e0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
84f0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
8500: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
8510: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
8520: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
8530: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
8540: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
8550: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
8560: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
8570: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
8580: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
8590: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
85a0: 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66  TE]. {END}.** If
85b0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
85c0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
85d0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
85e0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
85f0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8600: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
8610: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
8620: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
8630: 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  et..**.** {H1114
8640: 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  3} SQLite will a
8650: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8660: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8670: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
8680: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
8690: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
86a0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
86b0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
86c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
86d0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
86e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
86f0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
8700: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8710: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
8720: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8730: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
8740: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8750: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
8760: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
8770: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
8780: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8790: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
87a0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
87b0: 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a   </ul> {END}.**.
87c0: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
87d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
87e0: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
87f0: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
8800: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
8810: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
8820: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
8830: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
8840: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
8850: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
8860: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
8870: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
8880: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
8890: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
88a0: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
88b0: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
88c0: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
88d0: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
88e0: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
88f0: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
8900: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
8910: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
8920: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
8930: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
8940: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
8950: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
8960: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
8970: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
8980: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
8990: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
89a0: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
89b0: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
89c0: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
89d0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
89e0: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
89f0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8a00: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8a10: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
8a20: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8a30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8a40: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
8a50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
8a60: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
8a70: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  /ul>.**.** {H111
8a80: 34 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  45} The [SQLITE_
8a90: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8aa0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
8ab0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8ac0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
8ad0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
8ae0: 20 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53   {H11146} The [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8b00: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
8b10: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
8b20: 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f  P  databases, jo
8b30: 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73  urnals and for s
8b40: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
8b50: 2a 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b  * {H11147} The [
8b60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
8b70: 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e  USIVE] flag mean
8b80: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
8b90: 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66  d be opened.** f
8ba0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
8bb0: 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20  ess.  This flag 
8bc0: 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66  is set for all f
8bd0: 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66  iles except.** f
8be0: 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
8bf0: 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
8c00: 20 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61   {H11148} At lea
8c10: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
8c20: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
8c30: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
8c40: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
8c50: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
8c60: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
8c70: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
8c80: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
8c90: 78 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68  xOpen. {END}  Th
8ca0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
8cb0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
8cc0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
8cd0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
8ce0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
8cf0: 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  t in..**.** {H11
8d00: 31 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61  149} The flags a
8d10: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
8d20: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
8d30: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8d40: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
8d50: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
8d60: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
8d70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8d80: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
8d90: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8da0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
8db0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
8dc0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8dd0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
8de0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
8df0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
8e00: 6c 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66  le. {END}  The f
8e10: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
8e20: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
8e30: 20 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {H11150} SQLite
8e40: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8e50: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8e60: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
8e70: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
8e80: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
8e90: 50 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35  Pathname. {H1115
8ea0: 31 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  1} The exact siz
8eb0: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
8ec0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
8ed0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
8ee0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
8ef0: 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20   methods. {END} 
8f00: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
8f10: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
8f20: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
8f30: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
8f40: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
8f50: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
8f60: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
8f70: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
8f80: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
8f90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8fa0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
8fb0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
8fc0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
8fd0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
8fe0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
8ff0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
9000: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
9010: 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72  leep(), and xCur
9020: 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72  rentTime() inter
9030: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
9040: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
9050: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
9060: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
9070: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
9080: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
9090: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
90a0: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
90b0: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
90c0: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
90d0: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
90e0: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
90f0: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
9100: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
9110: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
9120: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
9130: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
9140: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
9150: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
9160: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
9170: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
9180: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
9190: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
91a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
91b0: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
91c0: 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54  .  The xCurrentT
91d0: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
91e0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
91f0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
9200: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
9210: 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79   and time..*/.ty
9220: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
9230: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
9240: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
9250: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
9260: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
9270: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
9280: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
9290: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
92a0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
92b0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
92c0: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
92d0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
92e0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
92f0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
9300: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
9310: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
9320: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
9330: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
9340: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9350: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9360: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9370: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9380: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9390: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
93a0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
93b0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
93c0: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
93d0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
93e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
93f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9400: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
9410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
9420: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
9430: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
9440: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9450: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9460: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9470: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9480: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9490: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
94a0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
94b0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
94c0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
94d0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
94e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
94f0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
9500: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
9510: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
9520: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
9530: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9540: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9550: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9560: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9570: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9580: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9590: 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c  d *(*xDlSym)(sql
95a0: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
95b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
95c0: 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a  mbol);.  void (*
95d0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
95e0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
95f0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9600: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9610: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9620: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9630: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9640: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9650: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9660: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9670: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9680: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
9690: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
96a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
96b0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
96c0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
96d0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
96e0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
96f0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
9700: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
9710: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
9720: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
9730: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
9740: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
9750: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
9760: 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d   method {H11190}
9770: 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20   <H11140>.**.** 
9780: 7b 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 69  {H11191} These i
9790: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
97a0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
97b0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
97c0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
97d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
97e0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
97f0: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20   object. {END}  
9800: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
9810: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
9820: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
9830: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
9840: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
9850: 20 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 53   {H11192} With S
9860: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9870: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
9880: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
9890: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
98a0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
98b0: 2e 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69  ..** {H11193} Wi
98c0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
98d0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
98e0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
98f0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
9900: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74   the file is bot
9910: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
9920: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31  ritable..** {H11
9930: 31 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45  194} With SQLITE
9940: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
9950: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
9960: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
9970: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
9980: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66  eadable..*/.#def
9990: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
99a0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
99b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
99c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a  ESS_READWRITE 1.
99d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
99e0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
99f0: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
9a00: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
9a10: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
9a20: 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30   {H10130} <S2000
9a30: 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
9a40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9a50: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9a60: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
9a70: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
9a80: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
9a90: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
9aa0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
9ab0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
9ac0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
9ad0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
9ae0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
9af0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
9b00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9b10: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
9b20: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
9b30: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
9b40: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
9b50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
9b60: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
9b70: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
9b80: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
9b90: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
9ba0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
9bb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9bc0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
9bd0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
9be0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
9bf0: 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65  ).  Only an effe
9c00: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
9c10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9c20: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
9c30: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
9c40: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
9c50: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
9c60: 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d  no-ops..**.** Am
9c70: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
9c80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
9c90: 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76  lize() shall inv
9ca0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
9cb0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
9cc0: 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68  arly, sqlite3_sh
9cd0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c  utdown().** shal
9ce0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
9cf0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
9d00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9d10: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9d20: 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
9d30: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  _OK on success..
9d40: 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  ** If for some r
9d50: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
9d60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
9d70: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
9d80: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
9d90: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
9da0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
9db0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
9dc0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
9dd0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
9de0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
9df0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
9e00: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a   SQLITE_OK..**.*
9e10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
9e20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
9e30: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
9e40: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
9e50: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
9e60: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
9e70: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
9e80: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
9e90: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
9ea0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
9eb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
9ec0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
9ed0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
9ee0: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
9ef0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9f00: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
9f10: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
9f20: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
9f30: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
9f40: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9f50: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
9f60: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
9f70: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
9f80: 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69  ady.  However, i
9f90: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
9fa0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
9fb0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
9fc0: 49 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  IT.** compile-ti
9fd0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
9fe0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
9ff0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
a000: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
a010: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
a020: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
a030: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
a040: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
a050: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
a060: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a070: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a080: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
a090: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
a0a0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
a0b0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
a0c0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
a0d0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
a0e0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
a0f0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
a100: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
a110: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
a120: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
a130: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
a140: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
a150: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
a160: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
a170: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
a180: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a190: 65 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f  ed with SQLITE_O
a1a0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67  MIT_AUTOINIT mig
a1b0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
a1c0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
a1d0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
a1e0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
a1f0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
a200: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a210: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
a220: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
a230: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
a240: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
a250: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
a260: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a270: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
a280: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
a290: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
a2a0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
a2b0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
a2c0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
a2d0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
a2e0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
a2f0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
a300: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
a310: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
a320: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
a330: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
a340: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
a350: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
a360: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
a370: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
a380: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
a390: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
a3a0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
a3b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
a3c0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
a3d0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
a3e0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
a3f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a400: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
a410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
a420: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
a430: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
a440: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
a450: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
a460: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
a470: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
a480: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
a490: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
a4a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a4b0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
a4c0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
a4d0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
a4e0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
a4f0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
a500: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
a510: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a520: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
a530: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
a540: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
a550: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
a560: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69  led for unix, wi
a570: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a  ndows, or os/2..
a580: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f  ** When built fo
a590: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
a5a0: 73 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c  s (using the SQL
a5b0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63  ITE_OS_OTHER=1 c
a5c0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
a5d0: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
a5e0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
a5f0: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
a600: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
a610: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
a620: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
a630: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
a640: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
a650: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
a660: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
a670: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
a680: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a690: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53  ** must return S
a6a0: 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
a6b0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
a6c0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
a6d0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
a6e0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
a6f0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
a700: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
a710: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
a720: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
a730: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
a740: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
a750: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
a760: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
a770: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
a780: 72 79 20 7b 48 31 30 31 34 35 7d 20 3c 53 32 30  ry {H10145} <S20
a790: 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20  000><S30200>.** 
a7a0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
a7b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a7c0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a7d0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
a7e0: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
a7f0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
a800: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
a810: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
a820: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
a830: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
a840: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
a850: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
a860: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
a870: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
a880: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
a890: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
a8a0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
a8b0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
a8c0: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
a8d0: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
a8e0: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
a8f0: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
a900: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
a910: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a920: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
a930: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
a940: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
a950: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
a960: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
a970: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
a980: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
a990: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
a9a0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
a9b0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
a9c0: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
a9d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
a9e0: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
a9f0: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
aa00: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
aa10: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
aa20: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
aa30: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
aa40: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
aa50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
aa60: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
aa70: 65 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33  er, that sqlite3
aa80: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
aa90: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
aaa0: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
aab0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
aac0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
aad0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
aae0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
aaf0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ab00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
ab10: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
ab20: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  er.** [SQLITE_CO
ab30: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
ab40: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
ab50: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
ab60: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
ab70: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
ab80: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
ab90: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
aba0: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
abb0: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
abc0: 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45  g on the [SQLITE
abd0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
abe0: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
abf0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
ac00: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
ac10: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
ac20: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
ac30: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
ac40: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ac50: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
ac60: 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f  _OK..** If the o
ac70: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
ac80: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
ac90: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
aca0: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
acb0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
acc0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
acd0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
ace0: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
acf0: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
ad00: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
ad10: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ad20: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
ad30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ad40: 73 20 20 7b 48 31 30 31 38 30 7d 20 3c 53 32 30  s  {H10180} <S20
ad50: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  000>.** EXPERIME
ad60: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
ad70: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ad80: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
ad90: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
ada0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
adb0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
adc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
add0: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
ade0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
adf0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ae00: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ae10: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ae20: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
ae30: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ae40: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
ae50: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
ae60: 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a  argument).  The.
ae70: 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  ** sqlite3_db_co
ae80: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
ae90: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
aea0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  d immediately af
aeb0: 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ter.** the datab
aec0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
aed0: 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
aee0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
aef0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
af00: 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
af10: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
af20: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63    .**.** The sec
af30: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
af40: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
af50: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
af60: 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  he.** configurat
af70: 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e  ion verb - an in
af80: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
af90: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a  indicates what.*
afa0: 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  * aspect of the 
afb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
afc0: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
afd0: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68  onfigured..** Th
afe0: 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f  e only choice fo
aff0: 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20  r this value is 
b000: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
b010: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20  _LOOKASIDE]..** 
b020: 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69  New verbs are li
b030: 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64  kely to be added
b040: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
b050: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
b060: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  * Additional arg
b070: 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e  uments depend on
b080: 20 74 68 65 20 76 65 72 62 2e 0a 2a 2f 0a 53 51   the verb..*/.SQ
b090: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
b0a0: 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  L int sqlite3_db
b0b0: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
b0c0: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
b0d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b0e0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
b0f0: 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 30  on Routines {H10
b100: 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a 2a  155} <S20120>.**
b110: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
b120: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
b130: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
b140: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
b150: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
b160: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
b170: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
b180: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
b190: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
b1a0: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
b1b0: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
b1c0: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
b1d0: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
b1e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
b1f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
b200: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b210: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
b220: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
b230: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
b240: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
b250: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b260: 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74 69  LOC].  By creati
b270: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
b280: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
b290: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
b2a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
b2b0: 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f 6e  ig()] during con
b2c0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a  figuration, an.*
b2d0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  * application ca
b2e0: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
b2f0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20  ernative memory 
b300: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
b310: 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69  stem.** for SQLi
b320: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
b330: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
b340: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
b350: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
b360: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
b370: 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f   a built-in memo
b380: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
b390: 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c  t is.** perfectl
b3a0: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
b3b0: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
b3c0: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
b3d0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
b3e0: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
b3f0: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
b400: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
b410: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
b420: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
b430: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
b440: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
b450: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
b460: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
b470: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
b480: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
b490: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
b4a0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
b4b0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
b4c0: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
b4d0: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
b4e0: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
b4f0: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
b500: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
b510: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
b520: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
b530: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
b540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
b550: 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20  loc, xFree, and 
b560: 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73  xRealloc methods
b570: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
b580: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
b590: 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65 61   free(), and rea
b5a0: 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 73  lloc() functions
b5b0: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
b5c0: 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a  rd library..**.*
b5d0: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
b5e0: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
b5f0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
b600: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
b610: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
b620: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
b630: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
b640: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
b650: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
b660: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
b670: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
b680: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
b690: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
b6a0: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
b6b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
b6c0: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
b6d0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
b6e0: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
b6f0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
b700: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
b710: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
b720: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
b730: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
b740: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b750: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
b760: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
b770: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
b780: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
b790: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
b7a0: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
b7b0: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a  power of 2..**.*
b7c0: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
b7d0: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
b7e0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
b7f0: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
b800: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
b810: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
b820: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
b830: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
b840: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
b850: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
b860: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
b870: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
b880: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
b890: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
b8a0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
b8b0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
b8c0: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
b8d0: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
b8e0: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
b8f0: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
b900: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
b910: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
b920: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70  Shutdown..*/.typ
b930: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
b940: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
b950: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b960: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
b970: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
b980: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
b990: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
b9a0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
b9b0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
b9c0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
b9d0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
b9e0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
b9f0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
ba00: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
ba10: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
ba20: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
ba30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
ba40: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
ba50: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
ba60: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
ba70: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
ba80: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
ba90: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
baa0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
bab0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
bac0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
bad0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
bae0: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
baf0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
bb00: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
bb10: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
bb20: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
bb30: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
bb40: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
bb50: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bb60: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
bb70: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
bb80: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
bb90: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
bba0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
bbb0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
bbc0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
bbd0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30  ion Options {H10
bbe0: 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  160} <S20000>.**
bbf0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
bc00: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
bc10: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
bc20: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
bc30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
bc40: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
bc50: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
bc60: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
bc70: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
bc80: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
bc90: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
bca0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bcb0: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
bcc0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
bcd0: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
bce0: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
bcf0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bd00: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
bd10: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
bd20: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
bd30: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
bd40: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
bd50: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
bd60: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
bd70: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
bd80: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
bd90: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
bda0: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
bdb0: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
bdc0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
bdd0: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
bde0: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
bdf0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
be00: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
be10: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
be20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
be30: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
be40: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
be50: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
be60: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
be70: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
be80: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
be90: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
bea0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
beb0: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
bec0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
bed0: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
bee0: 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  read.</dd>.**.**
bef0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
bf00: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
bf10: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
bf20: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
bf30: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
bf40: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64  .  This option d
bf50: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
bf60: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
bf70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
bf80: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
bf90: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
bfa0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
bfb0: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
bfc0: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
bfd0: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
bfe0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bff0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
c000: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
c010: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
c020: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
c030: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
c040: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
c050: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
c060: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
c070: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
c080: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
c090: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
c0a0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
c0b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c0c0: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
c0d0: 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b 74  ime.  See the [t
c0e0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a  hreading mode].*
c0f0: 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  * documentation 
c100: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
c110: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
c120: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c130: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
c140: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
c150: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
c160: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
c170: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
c180: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
c190: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
c1a0: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
c1b0: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
c1c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c1d0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
c1e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
c1f0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
c200: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
c210: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
c220: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
c230: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
c240: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
c250: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
c260: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
c270: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
c280: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
c290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c2a0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
c2b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
c2c0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
c2d0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
c2e0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
c2f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c300: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
c310: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
c320: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
c330: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
c340: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
c350: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
c360: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
c370: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
c380: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
c390: 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ation.</dd>.**.*
c3a0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c3b0: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
c3c0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c3d0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
c3e0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
c3f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
c400: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
c410: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
c420: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
c430: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
c440: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
c450: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
c460: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
c470: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
c480: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
c490: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
c4a0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
c4b0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
c4c0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
c4d0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c4e0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c4f0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
c500: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c510: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c520: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c530: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c540: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
c550: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
c560: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c570: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
c580: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
c590: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
c5a0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
c5b0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
c5c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c5d0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  on routines..** 
c5e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
c5f0: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
c600: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
c610: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c620: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
c630: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
c640: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
c650: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c660: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
c670: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
c680: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  e, for example.<
c690: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c6a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
c6b0: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
c6c0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c6d0: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
c6e0: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
c6f0: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
c700: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
c710: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
c720: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
c730: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
c740: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
c750: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57 68  * statistics. Wh
c760: 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  en disabled, the
c770: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
c780: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
c790: 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72  ome .** non-oper
c7a0: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
c7b0: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
c7c0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
c7d0: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
c7e0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
c7f0: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
c800: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
c810: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
c820: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
c830: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
c840: 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64  *   </ul>.** </d
c850: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c860: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
c870: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CH</dt>.** <dd>T
c880: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
c890: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
c8a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
c8b0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
c8c0: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
c8d0: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
c8e0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
c8f0: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  s:  A pointer to
c900: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65   the memory, the
c910: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
c920: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
c930: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
c940: 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20  mber of buffers 
c950: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
c960: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
c970: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
c980: 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65  6. The sz parame
c990: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
c9a0: 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72  few bytes.** lar
c9b0: 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63 74  ger than the act
c9c0: 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61 63  ual scratch spac
c9d0: 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20 69  e required due i
c9e0: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64  nternal overhead
c9f0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a 2a  ..** The first.*
ca00: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
ca10: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
ca20: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
ca30: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
ca40: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51  of memory..** SQ
ca50: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
ca60: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
ca70: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74  cratch buffer at
ca80: 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64   once per thread
ca90: 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64  , so.** N should
caa0: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65   be set to the e
cab0: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
cac0: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
cad0: 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61  s.  The sz.** pa
cae0: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
caf0: 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69  e 6 times the si
cb00: 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
cb10: 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  t database page 
cb20: 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68  size..** Scratch
cb30: 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65   buffers are use
cb40: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
cb50: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f   btree balance o
cb60: 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a  peration.  If.**
cb70: 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   The btree balan
cb80: 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69  cer needs additi
cb90: 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f  onal memory beyo
cba0: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
cbb0: 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63  ded by.** scratc
cbc0: 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20  h buffers or if 
cbd0: 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  no scratch buffe
cbe0: 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69  r space is speci
cbf0: 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74  fied, then SQLit
cc00: 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71  e.** goes to [sq
cc10: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
cc20: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
cc30: 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f  mory it needs.</
cc40: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
cc50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
cc60: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
cc70: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
cc80: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
cc90: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
cca0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
ccb0: 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
ccc0: 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
ccd0: 65 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  e.  There are th
cce0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
ccf0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
cd00: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
cd10: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
cd20: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
cd30: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
cd40: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
cd50: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75  e sz argument mu
cd60: 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66  st be a power of
cd70: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
cd80: 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65   and 32768.  The
cd90: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
cda0: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
cdb0: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
cdc0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
cdd0: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
cde0: 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  y..** SQLite wil
cdf0: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
ce00: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
ce10: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ce20: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
ce30: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
ce40: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
ce50: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
ce60: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20  s to cache.  If 
ce70: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
ce80: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
ce90: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
cea0: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
ceb0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
cec0: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
ced0: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
cee0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
cef0: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
cf00: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
cf10: 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
cf20: 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e  ion might use on
cf30: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
cf40: 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f   N buffers to ho
cf50: 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63  ld .** memory ac
cf60: 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61  counting informa
cf70: 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tion. </dd>.**.*
cf80: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cf90: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
cfa0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
cfb0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
cfc0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
cfd0: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
cfe0: 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
cff0: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
d000: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d010: 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
d020: 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
d030: 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
d040: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
d050: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
d060: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
d070: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
d080: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20  ee arguments: A 
d090: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
d0a0: 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65  emory, the numbe
d0b0: 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
d0c0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
d0d0: 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
d0e0: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
d0f0: 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ize.  If.** the 
d100: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
d110: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
d120: 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
d130: 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
d140: 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
d150: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
d160: 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
d170: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
d180: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
d190: 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
d1a0: 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
d1b0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
d1c0: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68  _MALLOC].  If th
d1d0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
d1e0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
d1f0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
d200: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
d210: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
d220: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
d230: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
d240: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
d250: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
d260: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
d270: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
d280: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
d290: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
d2a0: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
d2b0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d2c0: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
d2d0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
d2e0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d2f0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d300: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
d310: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
d320: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d330: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
d340: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
d350: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
d360: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
d370: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
d380: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
d390: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
d3a0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
d3b0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
d3c0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
d3d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d3e0: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
d3f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
d400: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
d410: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
d420: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d430: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
d440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
d450: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
d460: 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
d470: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d480: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
d490: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
d4a0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
d4b0: 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
d4c0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69  routines..** Thi
d4d0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
d4e0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
d4f0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
d500: 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
d510: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
d520: 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
d530: 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
d540: 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
d550: 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
d560: 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
d570: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
d580: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d590: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
d5a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d5b0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
d5c0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
d5d0: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
d5e0: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
d5f0: 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61   allcation looka
d600: 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  side optimizatio
d610: 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  n.  The first ar
d620: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
d630: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
d640: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
d650: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
d660: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
d670: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
d680: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
d690: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d6a0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
d6b0: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
d6c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
d6d0: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
d6e0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
d6f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d700: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
d710: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
d720: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d730: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
d740: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
d750: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d760: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
d770: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
d780: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
d790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d7a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
d7b0: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
d7c0: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
d7d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d7e0: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
d7f0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
d800: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
d810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d820: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
d830: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
d840: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
d850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d860: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
d870: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
d880: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
d890: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
d8a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d8b0: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
d8c0: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
d8d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d8e0: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
d8f0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
d900: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
d910: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d920: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
d930: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
d940: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
d950: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
d960: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
d970: 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f 2a  NKALLOC   12  /*
d980: 20 69 6e 74 20 74 68 72 65 73 68 6f 6c 64 20 2a   int threshold *
d990: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d9a0: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
d9b0: 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
d9c0: 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  int */../*.** CA
d9d0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
d9e0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
d9f0: 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10170} <S20000>.
da00: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
da10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
da20: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
da30: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
da40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
da50: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
da60: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
da70: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
da80: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
da90: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
daa0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
dab0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
dac0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
dad0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
dae0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
daf0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
db00: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
db10: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
db20: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
db30: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
db40: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
db50: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
db60: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
db70: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
db80: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
db90: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
dba0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
dbb0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
dbc0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
dbd0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
dbe0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
dbf0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
dc00: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
dc10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
dc20: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
dc30: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
dc40: 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
dc50: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
dc60: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
dc70: 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
dc80: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
dc90: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
dca0: 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
dcb0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
dcc0: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
dcd0: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
dce0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
dcf0: 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
dd00: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
dd10: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
dd20: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
dd30: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
dd40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
dd50: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
dd60: 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
dd70: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69   memory.  The fi
dd80: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
dd90: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
dda0: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
ddb0: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
ddc0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
ddd0: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
dde0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
ddf0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63  loc()].  The sec
de00: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
de10: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
de20: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
de30: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
de40: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
de50: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
de60: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
de70: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
de80: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
de90: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
dea0: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
deb0: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
dec0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
ded0: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
dee0: 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64  d arguments.</dd
def0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
df00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
df10: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
df20: 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76  DE    1001  /* v
df30: 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
df40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
df50: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
df60: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
df70: 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30  ult Codes {H1220
df80: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
df90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
dfa0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
dfb0: 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
dfc0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
dfd0: 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
dfe0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
dff0: 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
e000: 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  te. The extended
e010: 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
e020: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
e030: 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
e040: 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
e050: 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74  ility considerat
e060: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
e070: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
e080: 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20  12201} Each new 
e090: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e0a0: 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65  tion] shall have
e0b0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
e0c0: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
e0d0: 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
e0e0: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
e0f0: 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ault..**.** {H12
e100: 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  202} The [sqlite
e110: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
e120: 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e  t_codes(D,F)] in
e130: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e  terface shall en
e140: 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
e150: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
e160: 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65  t codes] for the
e170: 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
e180: 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
e190: 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20 70        if the F p
e1a0: 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75 65  arameter is true
e1b0: 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  , or disable the
e1c0: 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e  m if F is false.
e1d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e1e0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e1f0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
e200: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
e210: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
e220: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
e230: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
e240: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
e250: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
e260: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
e270: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
e280: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
e290: 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64  alled the "rowid
e2a0: 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  ". The rowid is 
e2b0: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
e2c0: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
e2d0: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
e2e0: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
e2f0: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
e300: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
e310: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
e320: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
e330: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
e340: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74  mns. If.** the t
e350: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
e360: 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45  n of type INTEGE
e370: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68  R PRIMARY KEY th
e380: 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
e390: 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
e3a0: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
e3b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
e3c0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
e3d0: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f   rowid of the mo
e3e0: 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
e3f0: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69  cessful INSERT i
e400: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
e410: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
e420: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
e430: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
e440: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
e450: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
e460: 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  RTs.** have ever
e470: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
e480: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
e490: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
e4a0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
e4b0: 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75  f an INSERT occu
e4c0: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
e4d0: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f  ger, then the ro
e4e0: 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72  wid of the inser
e4f0: 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
e500: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
e510: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
e520: 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
e530: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
e540: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
e550: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
e560: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e570: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
e580: 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
e590: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
e5a0: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
e5b0: 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
e5c0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54  .**.** An INSERT
e5d0: 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
e5e0: 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
e5f0: 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
e600: 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
e610: 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f 65 73   INSERT and does
e620: 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
e630: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
e640: 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
e650: 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
e660: 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
e670: 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
e680: 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
e690: 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
e6a0: 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
e6b0: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
e6c0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
e6d0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
e6e0: 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
e6f0: 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
e700: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
e710: 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
e720: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
e730: 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
e740: 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
e750: 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
e760: 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
e770: 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
e780: 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
e790: 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
e7a0: 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
e7b0: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
e7c0: 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
e7d0: 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
e7e0: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
e7f0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
e800: 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
e810: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
e820: 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20 63 6f   an INSERT is co
e830: 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
e840: 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
e850: 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
e860: 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
e870: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
e880: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
e890: 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2221} The [sqlit
e8a0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
e8b0: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e  owid()] function
e8c0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77   returns the row
e8d0: 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  id.**          o
e8e0: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
e8f0: 74 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  t successful INS
e900: 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e  ERT performed on
e910: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
e920: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
e930: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
e940: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
e950: 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a  or higher level.
e960: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
e970: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
e980: 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
e990: 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69  ve been no quali
e9a0: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a  fying inserts..*
e9b0: 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68  *.** {H12223} Th
e9c0: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
e9d0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
e9e0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e9f0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
ea00: 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e   same value when
ea10: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
ea20: 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f   same trigger co
ea30: 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20  ntext.**        
ea40: 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65    immediately be
ea50: 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61  fore and after a
ea60: 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a   ROLLBACK..**.**
ea70: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
ea80: 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 20  .** {A12232} If 
ea90: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
eaa0: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
eab0: 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65 20 73   INSERT on the s
eac0: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
ead0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
eae0: 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
eaf0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
eb00: 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20  rt_rowid()].**  
eb10: 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
eb20: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
eb30: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
eb40: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
eb50: 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  id,.**          
eb60: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
eb70: 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
eb80: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
eb90: 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20  rowid()] is.**  
eba0: 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63          unpredic
ebb0: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
ebc0: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
ebd0: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
ebe0: 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
ebf0: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
ec00: 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  d..*/.sqlite3_in
ec10: 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
ec20: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
ec30: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
ec40: 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
ec50: 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
ec60: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32  ws Modified {H12
ec70: 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a  240} <S10600>.**
ec80: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
ec90: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
eca0: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
ecb0: 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
ecc0: 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
ecd0: 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
ece0: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
ecf0: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
ed00: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
ed10: 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
ed20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
ed30: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
ed40: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
ed50: 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  .** Only changes
ed60: 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
ed70: 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
ed80: 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
ed90: 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54 45  TE,.** or DELETE
eda0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
edb0: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
edc0: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
edd0: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
ede0: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
edf0: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
ee00: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
ee10: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
ee20: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
ee30: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
ee40: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
ee50: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
ee60: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
ee70: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
ee80: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
ee90: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
eea0: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
eeb0: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
eec0: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
eed0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
eee0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
eef0: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
ef00: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
ef10: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
ef20: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
ef30: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
ef40: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
ef50: 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
ef60: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
ef70: 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
ef80: 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
ef90: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
efa0: 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
efb0: 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
efc0: 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
efd0: 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
efe0: 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
eff0: 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
f000: 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
f010: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
f020: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
f030: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
f040: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
f050: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
f060: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
f070: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
f080: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
f090: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
f0a0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
f0b0: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
f0c0: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
f0d0: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
f0e0: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
f0f0: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
f100: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
f110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
f120: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
f130: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
f140: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
f150: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
f160: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
f170: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
f180: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f190: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f1a0: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
f1b0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
f1c0: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
f1d0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
f1e0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
f1f0: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
f200: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
f210: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
f220: 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c   Thus, when call
f230: 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
f240: 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
f250: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
f260: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
f270: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
f280: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
f290: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
f2a0: 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
f2b0: 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
f2c0: 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68  top level.  With
f2d0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
f2e0: 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
f2f0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
f300: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
f310: 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
f320: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
f330: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
f340: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
f350: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
f360: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
f370: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
f380: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
f390: 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
f3a0: 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
f3b0: 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
f3c0: 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
f3d0: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
f3e0: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
f3f0: 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
f400: 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
f410: 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
f420: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
f430: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
f440: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f450: 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
f460: 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
f470: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
f480: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
f490: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
f4a0: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
f4b0: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
f4c0: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
f4d0: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
f4e0: 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65  s from the table
f4f0: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  .)  Because of t
f500: 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74  his.** optimizat
f510: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
f520: 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52  ns in "DELETE FR
f530: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f  OM table" are no
f540: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e  t row changes an
f550: 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65  d.** will not be
f560: 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20   counted by the 
f570: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f580: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f  ) or [sqlite3_to
f590: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a  tal_changes()].*
f5a0: 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67  * functions, reg
f5b0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
f5c0: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
f5d0: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
f5e0: 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65  inally.** in the
f5f0: 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20   table.  To get 
f600: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
f610: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
f620: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
f630: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
f640: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
f650: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
f660: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
f670: 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 68  *.** {H12241} Th
f680: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
f690: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  es()] function s
f6a0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  hall return the 
f6b0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
f6c0: 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65        row change
f6d0: 73 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20  s caused by the 
f6e0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
f6f0: 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20  RT, UPDATE,.**  
f700: 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54          or DELET
f710: 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  E statement on t
f720: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
f730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a   connection and.
f740: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
f750: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68  in the same or h
f760: 69 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f  igher trigger co
f770: 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69  ntext, or zero i
f780: 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20  f there have.** 
f790: 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65           not bee
f7a0: 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67  n any qualifying
f7b0: 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a   row changes..**
f7c0: 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 61  .** {H12243} Sta
f7d0: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
f7e0: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
f7f0: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
f800: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
f810: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
f820: 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75  ll cause subsequ
f830: 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
f840: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
f850: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20  3_changes()] to 
f860: 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67  return zero, reg
f870: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a  ardless of the.*
f880: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
f890: 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e  r of rows origin
f8a0: 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c  ally in the tabl
f8b0: 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  e..**.** ASSUMPT
f8c0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
f8d0: 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  252} If a separa
f8e0: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
f8f0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
f900: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
f910: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
f920: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
f930: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
f940: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
f950: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
f960: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
f970: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
f980: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
f990: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f9a0: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
f9b0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
f9c0: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
f9d0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
f9e0: 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30  ed {H12260} <S10
f9f0: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
fa00: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
fa10: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
fa20: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
fa30: 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20  d by INSERT,.** 
fa40: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
fa50: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
fa60: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
fa70: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
fa80: 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63  opened..** The c
fa90: 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c  ount includes al
faa0: 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61  l changes from a
fab0: 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ll trigger conte
fac0: 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  xts.  However,.*
fad0: 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
fae0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
faf0: 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
fb00: 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63  lement REPLACE c
fb10: 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
fb20: 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
fb30: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
fb40: 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70   or DROP table p
fb50: 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68  rocessing..** Th
fb60: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
fb70: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
fb80: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
fb90: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
fba0: 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28  s.** completed (
fbb0: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
fbc0: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73  nt handle is pas
fbd0: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
fbe0: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
fbf0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
fc00: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ()])..**.** SQLi
fc10: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
fc20: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
fc30: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
fc40: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
fc50: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
fc60: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
fc70: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
fc80: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
fc90: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
fca0: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
fcb0: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
fcc0: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
fcd0: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
fce0: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
fcf0: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
fd00: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22  e deletions in "
fd10: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
fd20: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
fd30: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69  hanges and.** wi
fd40: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
fd50: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
fd60: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
fd70: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
fd80: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  nges()].** funct
fd90: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73  ions, regardless
fda0: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
fdb0: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
fdc0: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  were originally.
fdd0: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ** in the table.
fde0: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75    To get an accu
fdf0: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
fe00: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
fe10: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
fe20: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
fe30: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
fe40: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tead..**.** See 
fe50: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
fe60: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
fe70: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  erface..**.** IN
fe80: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
fe90: 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71  {H12261} The [sq
fea0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
feb0: 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74  ges()] returns t
fec0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a  he total number.
fed0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 72  **          of r
fee0: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
fef0: 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44  d by INSERT, UPD
ff00: 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45  ATE, and/or DELE
ff10: 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  TE.**          s
ff20: 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65  tatements on the
ff30: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
ff40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20  connection], in 
ff50: 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  any.**          
ff60: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
ff70: 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
ff80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
ff90: 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a  as created..**.*
ffa0: 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61 74 65  * {H12263} State
ffb0: 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  ments of the for
ffc0: 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  m "DELETE FROM t
ffd0: 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e  ablename" with n
ffe0: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48  o.**          WH
fff0: 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c  ERE clause shall
10000 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
10010 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
10020 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
10030 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
10040 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  nges()]..**.** A
10050 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
10060 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20 61 20  * {A12264} If a 
10070 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
10080 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
10090 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
100a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
100b0 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
100c0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
100d0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
100e0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
100f0 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
10100 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
10110 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
10120 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
10130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
10140 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
10150 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
10160 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
10170 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
10180 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20 3c  Query {H12270} <
10190 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30500>.**.** Th
101a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
101b0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
101c0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
101d0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
101e0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
101f0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
10200 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
10210 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
10220 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
10230 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
10240 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
10250 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
10260 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
10270 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
10280 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
10290 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
102a0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
102b0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61  ..**.** It is sa
102c0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
102d0 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
102e0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
102f0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
10300 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
10310 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
10320 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
10330 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
10340 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
10350 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
10360 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
10370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
10380 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
10390 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
103a0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
103b0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
103c0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53  s..**.** If an S
103d0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
103e0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
103f0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
10400 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
10410 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
10420 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
10430 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
10440 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
10450 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
10460 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
10470 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
10480 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51  ion..**.** An SQ
10490 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
104a0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
104b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
104c0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
104d0 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72 72  ** If the interr
104e0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
104f0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
10500 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
10510 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
10520 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
10530 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
10540 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
10550 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
10560 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
10570 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
10580 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10590 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
105a0 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65  pt() has no effe
105b0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
105c0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
105d0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 73   started after s
105e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
105f0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
10600 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10610 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54 68 65  .** {H12271} The
10620 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
10630 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  upt()] interface
10640 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20   will force all 
10650 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  running.**      
10660 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
10670 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
10680 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  th the same data
10690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
106a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 68  **          to h
106b0 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65 73  alt after proces
106c0 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65  sing at most one
106d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20   additional row 
106e0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b  of data..**.** {
106f0 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20  H12272} Any SQL 
10700 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69  statement that i
10710 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62 79  s interrupted by
10720 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
10730 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  upt()].**       
10740 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b     will return [
10750 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
10760 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  ]..**.** ASSUMPT
10770 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
10780 32 37 39 7d 20 49 66 20 74 68 65 20 64 61 74 61  279} If the data
10790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
107a0 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
107b0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
107c0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
107d0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
107e0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
107f0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
10800 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
10810 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
10820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10830 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
10840 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
10850 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48  t Is Complete {H
10860 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a  10510} <S70200>.
10870 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
10880 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
10890 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  for command-line
108a0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
108b0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
108c0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
108d0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
108e0 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51  rm complete a SQ
108f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
10900 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
10910 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
10920 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
10930 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
10940 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
10950 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ng.  These routi
10960 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  nes return true 
10970 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
10980 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
10990 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
109a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
109b0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
109c0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
109d0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
109e0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
109f0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
10a00 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20   not a fragment 
10a10 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54  of a.** CREATE T
10a20 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
10a30 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68  .  Semicolons th
10a40 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
10a50 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
10a60 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
10a70 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
10a80 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
10a90 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
10aa0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
10ab0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
10ac0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
10ad0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
10ae0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
10af0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
10b00 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
10b10 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
10b20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
10b30 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
10b40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
10b50 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
10b60 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
10b70 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
10b80 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  SQL..**.** INVAR
10b90 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
10ba0 30 35 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  0511} A successf
10bb0 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  ul evaluation of
10bc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10bd0 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  te()] or.**     
10be0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
10bf0 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75 6e 63  mplete16()] func
10c00 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20 20  tions shall.**  
10c10 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61          return a
10c20 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20 61 6e   numeric 1 if an
10c30 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61  d only if the la
10c40 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63  st non-whitespac
10c50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  e.**          to
10c60 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70  ken in their inp
10c70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f  ut is a semicolo
10c80 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69 6e  n that is not in
10c90 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20 20   between.**     
10ca0 20 20 20 20 20 74 68 65 20 42 45 47 49 4e 20 61       the BEGIN a
10cb0 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41  nd END of a CREA
10cc0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
10cd0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ment..**.** {H10
10ce0 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79  512} If a memory
10cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
10d00 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
10d10 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a  an invocation.**
10d20 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b 73 71            of [sq
10d30 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
10d40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ] or [sqlite3_co
10d50 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68 65 6e  mplete16()] then
10d60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
10d70 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
10d80 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
10d90 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  MEM]..**.** ASSU
10da0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
10db0 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75  A10512} The inpu
10dc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10dd0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
10de0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
10df0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
10e00 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
10e10 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54 68 65  .** {A10513} The
10e20 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
10e30 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
10e40 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
10e50 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
10e60 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73 74         UTF-16 st
10e70 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
10e80 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
10e90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
10ea0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
10eb0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
10ec0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
10ed0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
10ee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
10ef0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
10f00 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
10f10 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
10f20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30  {H12310} <S40400
10f30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
10f40 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
10f50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
10f60 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
10f70 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
10f80 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
10f90 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
10fa0 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
10fb0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
10fc0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
10fd0 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
10fe0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
10ff0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
11000 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
11010 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
11020 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
11030 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
11040 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
11050 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
11060 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  . If the busy ca
11070 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
11080 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
11090 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
110a0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
110b0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
110c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
110d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
110e0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
110f0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
11100 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
11110 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
11120 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
11130 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54  sy_handler().  T
11140 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
11150 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
11160 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
11170 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
11180 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
11190 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
111a0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
111b0 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
111c0 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a  event.  If the.*
111d0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
111e0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
111f0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
11200 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
11210 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
11220 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
11230 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
11240 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
11250 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
11260 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
11270 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
11280 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
11290 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
112a0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
112b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
112c0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
112d0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
112e0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
112f0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
11300 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
11310 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
11320 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
11330 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
11340 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
11350 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  . If SQLite dete
11360 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
11370 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
11380 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
11390 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
113a0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
113b0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
113c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
113d0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
113e0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
113f0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
11400 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11410 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
11420 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
11430 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
11440 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
11450 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
11460 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
11470 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
11480 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
11490 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
114a0 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
114b0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
114c0 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
114d0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
114e0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
114f0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
11500 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
11510 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
11520 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
11530 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
11540 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
11550 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
11560 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
11570 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
11580 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
11590 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
115a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
115b0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
115c0 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
115d0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
115e0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
115f0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
11600 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
11610 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
11620 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
11630 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
11640 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
11650 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
11660 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
11670 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
11680 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
11690 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
116a0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
116b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
116c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
116d0 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
116e0 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
116f0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
11700 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
11710 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
11720 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
11730 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
11740 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
11750 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
11760 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
11770 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
11780 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
11790 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
117a0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
117b0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
117c0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
117d0 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
117e0 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
117f0 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
11800 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
11810 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
11820 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
11830 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
11840 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
11850 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
11860 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
11870 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
11880 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
11890 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
118a0 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
118b0 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
118c0 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
118d0 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
118e0 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
118f0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
11900 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
11910 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
11920 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
11930 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
11940 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
11950 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
11960 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
11970 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
11980 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
11990 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
119a0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
119b0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
119c0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
119d0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
119e0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
119f0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
11a00 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
11a10 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  portant..**.** T
11a20 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
11a30 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
11a40 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
11a50 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
11a60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11a70 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
11a80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
11a90 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
11aa0 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
11ab0 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63  er.  Note that c
11ac0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
11ad0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
11ae0 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
11af0 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
11b00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
11b10 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
11b20 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
11b30 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
11b40 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
11b50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
11b60 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
11b70 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
11b80 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
11b90 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
11ba0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
11bb0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
11bc0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
11bd0 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68 65 20  ** {H12311} The 
11be0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
11bf0 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20 66 75  ndler(D,C,A)] fu
11c00 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 70  nction shall rep
11c10 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lace.**         
11c20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
11c30 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
11c40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 69  connection] D wi
11c50 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  th a new.**     
11c60 20 20 20 20 20 61 20 6e 65 77 20 62 75 73 79 20       a new busy 
11c70 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61 70  handler C and ap
11c80 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
11c90 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20  ointer A..**.** 
11ca0 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79 20 63  {H12312} Newly c
11cb0 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73 65  reated [database
11cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68   connections] sh
11cd0 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73 79 0a  all have a busy.
11ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
11cf0 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ler of NULL..**.
11d00 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68 65 6e  ** {H12314} When
11d10 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b 64 61   two or more [da
11d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11d30 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a 20 20  ns] share a.**  
11d40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
11d50 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
11d60 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61  ache | common ca
11d70 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  che],.**        
11d80 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c    the busy handl
11d90 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
11da0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
11db0 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a  urrently using.*
11dc0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
11dd0 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20 69 6e  ache shall be in
11de0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63  voked when the c
11df0 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  ache encounters 
11e00 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  a lock..**.** {H
11e10 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79  12316} If a busy
11e20 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
11e30 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  k returns zero, 
11e40 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 20  then the SQLite 
11e50 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20  interface.**    
11e60 20 20 20 20 20 20 74 68 61 74 20 70 72 6f 76 6f        that provo
11e70 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20  ked the locking 
11e80 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74 75  event shall retu
11e90 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
11ea0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 38 7d  ..**.** {H12318}
11eb0 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20 69 6e   SQLite shall in
11ec0 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68  vokes the busy h
11ed0 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20  andler with two 
11ee0 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68 0a  arguments which.
11ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
11f00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f  a copy of the po
11f10 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20 62  inter supplied b
11f20 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  y the 3rd parame
11f30 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
11f40 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
11f50 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20  _handler()] and 
11f60 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  a count of the n
11f70 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a  umber of prior.*
11f80 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63  *          invoc
11f90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  ations of the bu
11fa0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74  sy handler for t
11fb0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
11fc0 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  event..**.** ASS
11fd0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
11fe0 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73 79 20  {A12319} A busy 
11ff0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
12000 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
12010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
12020 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70  *          or [p
12030 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12040 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
12050 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12060 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12070 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
12080 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
12090 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
120a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
120b0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
120c0 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d 20  imeout {H12340} 
120d0 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40410>.**.** T
120e0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
120f0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
12100 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
12110 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
12120 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
12130 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
12140 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
12150 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
12160 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
12170 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
12180 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
12190 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
121a0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
121b0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
121c0 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 33  cumulated. {H123
121d0 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20 6d  43} After "ms" m
121e0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
121f0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
12200 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
12210 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
12220 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
12230 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
12240 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
12250 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12260 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  KED]..**.** Call
12270 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
12280 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
12290 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
122a0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
122b0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
122c0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
122d0 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
122e0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
122f0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
12300 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
12310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12320 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
12330 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
12340 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
12350 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
12360 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
12370 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
12380 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
12390 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
123a0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
123b0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
123c0 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a  s cleared..**.**
123d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
123e0 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68 65 20  ** {H12341} The 
123f0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
12400 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f  meout()] functio
12410 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65  n shall override
12420 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20   any prior.**   
12430 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
12440 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
12450 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  or [sqlite3_busy
12460 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74  _handler()] sett
12470 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
12480 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
12490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
124a0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 33  ]..**.** {H12343
124b0 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  } If the 2nd par
124c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
124d0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
124e0 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a  )] is less than.
124f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65  **          or e
12500 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68  qual to zero, th
12510 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  en the busy hand
12520 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63 6c 65  ler shall be cle
12530 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20  ared so that.** 
12540 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62           all sub
12550 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20  sequent locking 
12560 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65  events immediate
12570 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ly return [SQLIT
12580 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_BUSY]..**.** {
12590 48 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32  H12344} If the 2
125a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
125b0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
125c0 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f  meout()] is a po
125d0 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
125e0 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65     number N, the
125f0 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  n a busy handler
12600 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20 74 68   shall be set th
12610 61 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61  at repeatedly ca
12620 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
12630 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
12640 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71 6c 69  hod in the [sqli
12650 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20 69 6e  te3_vfs | VFS in
12660 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c 0a 2a  terface] until.*
12670 2a 20 20 20 20 20 20 20 20 20 20 65 69 74 68 65  *          eithe
12680 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65 61 72  r the lock clear
12690 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63  s or until the c
126a0 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20  umulative sleep 
126b0 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  time.**         
126c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 62   reported back b
126d0 79 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65  y xSleep() excee
126e0 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  ds N millisecond
126f0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
12700 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
12710 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
12720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12730 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
12740 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
12750 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31 32  ing Queries {H12
12760 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  370} <S10000>.**
12770 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
12780 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
12790 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
127a0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
127b0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
127c0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
127d0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
127e0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
127f0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
12800 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
12810 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
12820 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
12830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
12840 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
12850 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
12860 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
12870 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
12880 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
12890 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
128a0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
128b0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
128c0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
128d0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
128e0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
128f0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
12900 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
12910 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
12920 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
12930 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
12940 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
12950 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
12960 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
12970 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
12980 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
12990 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
129a0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
129b0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
129c0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
129d0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
129e0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
129f0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
12a00 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
12a10 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
12a20 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
12a30 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
12a40 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
12a50 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
12a60 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
12a70 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
12a80 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
12a90 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
12aa0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
12ab0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
12ac0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
12ad0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
12ae0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
12af0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
12b00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
12b10 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
12b20 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
12b30 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
12b40 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
12b50 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
12b60 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
12b70 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
12b80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
12b90 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
12ba0 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70  *.** As an examp
12bb0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
12bc0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
12bd0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
12be0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
12bf0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
12c00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12c10 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
12c20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
12c30 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
12c40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
12c50 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
12c60 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
12c70 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
12c80 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
12c90 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
12ca0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
12cb0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
12cc0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
12cd0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
12ce0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
12cf0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
12d00 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
12d10 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
12d20 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12d30 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
12d40 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
12d50 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
12d60 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
12d70 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
12d80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12d90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
12da0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
12db0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
12dc0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12dd0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
12de0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
12df0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
12e00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12e10 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
12e20 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
12e30 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
12e40 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
12e50 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
12e60 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
12e70 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12e80 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
12e90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12ea0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
12eb0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12ec0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
12ed0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12ee0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
12ef0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
12f00 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
12f10 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
12f20 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
12f30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12f40 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
12f50 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
12f60 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72  meter.  It retur
12f70 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
12f80 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
12f90 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
12fa0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
12fb0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
12fc0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
12fd0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
12fe0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20  ing the result, 
12ff0 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73  it should.** pas
13000 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  s the pointer to
13010 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13020 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  e to sqlite3_fre
13030 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
13040 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
13050 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
13060 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
13070 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
13080 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
13090 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
130a0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
130b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
130c0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
130d0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
130e0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
130f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
13100 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
13110 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
13120 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
13130 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
13140 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
13150 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
13160 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
13170 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
13180 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
13190 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
131a0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
131b0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
131c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
131d0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
131e0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
131f0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
13200 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
13210 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
13220 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
13230 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
13240 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
13250 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
13260 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
13270 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
13280 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
13290 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
132a0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
132b0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
132c0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
132d0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
132e0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
132f0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
13300 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
13310 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  g()]..**.** INVA
13320 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
13330 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c  12371} If a [sql
13340 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13350 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79  ] fails a memory
13360 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
13370 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
13380 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68 65 20   shall free the 
13390 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64  result table und
133a0 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c  er construction,
133b0 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 20 20   abort the.**   
133c0 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20         query in 
133d0 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 61 6e  process, skip an
133e0 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65  y subsequent que
133f0 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a 2a 2a  ries, set the.**
13400 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a 52 65            *pazRe
13410 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69 6e  sult output poin
13420 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20  ter to NULL and 
13430 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
13440 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  OMEM]..**.** {H1
13450 32 33 37 33 7d 20 49 66 20 74 68 65 20 70 6e 43  2373} If the pnC
13460 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20  olumn parameter 
13470 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  to [sqlite3_get_
13480 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20  table()] is not 
13490 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
134a0 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66   then a successf
134b0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
134c0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
134d0 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20  ble()] shall.** 
134e0 20 20 20 20 20 20 20 20 20 77 72 69 74 65 20 74           write t
134f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
13500 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  umns in the.**  
13510 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
13520 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
13530 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a  into *pnColumn..
13540 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d 20 49  **.** {H12374} I
13550 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61 72 61  f the pnRow para
13560 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
13570 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
13580 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
13590 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75         then a su
135a0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
135b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
135c0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61  get_table()] sha
135d0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ll.**          w
135e0 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65 72  rites the number
135f0 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a   of rows in the.
13600 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
13610 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
13620 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e  ery into *pnRow.
13630 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36 7d 20  .**.** {H12376} 
13640 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
13650 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
13660 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
13670 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73 0a 2a   that computes.*
13680 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72 6f 77  *          N row
13690 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69 74 68  s of result with
136a0 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 20 72   C columns per r
136b0 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 2a 70  ow shall make *p
136c0 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  azResult.**     
136d0 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 61 6e       point to an
136e0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
136f0 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 73 74  rs to (N+1)*C st
13700 72 69 6e 67 73 20 77 68 65 72 65 20 74 68 65 20  rings where the 
13710 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
13720 20 20 43 20 73 74 72 69 6e 67 73 20 61 72 65 20    C strings are 
13730 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73 20  column names as 
13740 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
13750 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13760 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
13770 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74 20 61  ] and the rest a
13780 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74  re column result
13790 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
137a0 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f      obtained fro
137b0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
137c0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
137d0 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20 76 61   {H12379} The va
137e0 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61 7a 52  lues in the pazR
137f0 65 73 75 6c 74 20 61 72 72 61 79 20 72 65 74 75  esult array retu
13800 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
13810 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
13820 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
13830 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e 74  remain valid unt
13840 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b 73  il cleared by [s
13850 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
13860 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
13870 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 72 72  382} When an err
13880 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
13890 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b   evaluation of [
138a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
138b0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
138c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68   the function sh
138d0 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73 75  all set *pazResu
138e0 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 69 74  lt to NULL, writ
138f0 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  e an error messa
13900 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ge.**          i
13910 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
13920 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
13930 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b  3_malloc()], mak
13940 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 2a  e.**          **
13950 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 20 74  pzErrmsg point t
13960 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d 65 73  o that error mes
13970 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75 72 6e  sage, and return
13980 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   a.**          a
13990 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
139a0 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
139b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
139c0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
139d0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
139e0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
139f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
13a00 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
13a10 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
13a20 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
13a30 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
13a40 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
13a50 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
13a60 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
13a70 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
13a80 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
13a90 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
13aa0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
13ab0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
13ac0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
13ad0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
13ae0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
13af0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
13b00 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
13b10 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
13b20 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
13b30 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
13b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
13b50 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
13b60 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
13b70 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30   {H17400} <S7000
13b80 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  0><S20000>.**.**
13b90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
13ba0 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f  are workalikes o
13bb0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
13bc0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
13bd0 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
13be0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
13bf0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ary..**.** The s
13c00 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
13c10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
13c20 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
13c30 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
13c40 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
13c50 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
13c60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13c70 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
13c80 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
13c90 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
13ca0 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
13cb0 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
13cc0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
13cd0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
13ce0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
13cf0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
13d00 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
13d10 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
13d20 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
13d30 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
13d40 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
13d50 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
13d60 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
13d70 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
13d80 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
13d90 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
13da0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
13db0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
13dc0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
13dd0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
13de0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
13df0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
13e00 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
13e10 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
13e20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
13e30 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
13e40 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
13e50 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
13e60 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
13e70 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
13e80 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
13e90 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
13ea0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
13eb0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
13ec0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
13ed0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
13ee0 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
13ef0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13f00 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
13f10 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
13f20 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
13f30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13f40 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
13f50 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
13f60 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
13f70 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
13f80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13f90 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
13fa0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
13fb0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
13fc0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
13fd0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
13fe0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13ff0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
14000 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
14010 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
14020 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
14030 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
14040 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
14050 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
14060 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
14070 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
14080 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
14090 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
140a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
140b0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
140c0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
140d0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
140e0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
140f0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
14100 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
14110 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
14120 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
14130 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
14140 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
14150 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
14160 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
14170 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14180 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
14190 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
141a0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
141b0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
141c0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
141d0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
141e0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
141f0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
14200 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
14210 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
14220 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
14230 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
14240 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
14250 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
14260 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
14270 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
14280 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
14290 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
142a0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
142b0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
142c0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
142d0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
142e0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
142f0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
14300 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
14310 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
14320 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
14330 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
14340 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
14350 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
14360 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
14370 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
14380 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
14390 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
143a0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
143b0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
143c0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
143d0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
143e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
143f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
14400 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
14410 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
14420 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14430 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
14440 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
14450 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
14460 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
14470 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
14480 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
14490 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
144a0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
144b0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
144c0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
144d0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
144e0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
144f0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
14500 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
14510 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14520 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
14530 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
14540 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
14550 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
14560 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
14570 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
14580 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
14590 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
145a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
145b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
145c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
145d0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
145e0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
145f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14600 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
14610 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
14620 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
14630 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
14640 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
14650 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
14660 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
14670 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14680 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
14690 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
146a0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
146b0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
146c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
146d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
146e0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
146f0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
14700 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
14710 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
14720 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
14730 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
14740 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
14750 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
14760 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
14770 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
14780 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
14790 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
147a0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
147b0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
147c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
147d0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
147e0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
147f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
14800 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
14810 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
14820 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
14830 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
14840 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
14850 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20   single quotes) 
14860 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
14870 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20  %Q option.  So, 
14880 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
14890 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
148a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
148b0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
148c0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
148d0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
148e0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
148f0 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
14900 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
14910 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
14920 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
14930 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
14940 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14950 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
14960 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
14970 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
14980 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
14990 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
149a0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
149b0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
149c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
149d0 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66  **.** The "%z" f
149e0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
149f0 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c   works exactly l
14a00 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68  ike "%s" with th
14a10 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
14a20 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
14a30 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
14a40 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
14a50 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
14a60 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
14a70 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
14a80 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
14a90 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56   {END}.**.** INV
14aa0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
14ab0 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71  H17403}  The [sq
14ac0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
14ad0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d   and [sqlite3_vm
14ae0 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
14af0 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  aces.**         
14b00 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20    return either 
14b10 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
14b20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
14b30 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69  8 strings held i
14b40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  n.**           m
14b50 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
14b60 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
14b70 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70  loc()] or NULL p
14b80 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20  ointers if.**   
14b90 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74          a call t
14ba0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
14bb0 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  c()] fails..**.*
14bc0 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68 65 20  * {H17406}  The 
14bd0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
14be0 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  f()] interface w
14bf0 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72  rites a zero-ter
14c00 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
14c10 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
14c20 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  g into the buffe
14c30 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  r pointed to by 
14c40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14c50 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
14c60 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20    provided that 
14c70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14c80 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74  ter is greater t
14c90 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  han zero..**.** 
14ca0 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73  {H17407}  The [s
14cb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14cc0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
14cd0 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f 74  s not write slot
14ce0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
14cf0 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 66    its output buf
14d00 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20  fer (the second 
14d10 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69  parameter) outsi
14d20 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20  de the range.** 
14d30 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 74            of 0 t
14d40 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72  hrough N-1 (wher
14d50 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 74  e N is the first
14d60 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20   parameter).**  
14d70 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 6c           regardl
14d80 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74  ess of the lengt
14d90 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a  h of the string.
14da0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 71  **           req
14db0 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66 6f  uested by the fo
14dc0 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 69  rmat specificati
14dd0 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  on..*/.char *sql
14de0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
14df0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
14e00 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
14e10 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
14e20 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
14e30 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
14e40 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
14e50 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
14e60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14e70 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14e80 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48  ion Subsystem {H
14e90 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17300} <S20000>.
14ea0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
14eb0 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73   core  uses thes
14ec0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
14ed0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
14ee0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
14ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14f00 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
14f10 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
14f20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
14f30 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
14f40 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
14f50 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
14f60 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
14f70 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
14f80 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
14f90 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
14fa0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
14fb0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
14fc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
14fd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
14fe0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
14ff0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
15000 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
15010 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
15020 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
15030 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c  meter..** If sql
15040 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
15050 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
15060 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
15070 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
15080 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
15090 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20  ointer.  If the 
150a0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
150b0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
150c0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
150d0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
150e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
150f0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
15100 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61  ointer..**.** Ca
15110 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
15120 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
15130 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
15140 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
15150 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
15160 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
15170 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
15180 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
15190 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
151a0 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c  reused.  The sql
151b0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
151c0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
151d0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
151e0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
151f0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
15200 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
15210 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
15220 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
15230 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
15240 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
15250 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
15260 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
15270 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
15280 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
15290 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
152a0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
152b0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
152c0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
152d0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
152e0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
152f0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
15300 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
15310 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
15320 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
15330 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
15340 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
15350 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
15360 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
15370 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
15380 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
15390 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a  ite3_free()..**.
153a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
153b0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
153c0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
153d0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
153e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
153f0 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
15400 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
15410 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
15420 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
15430 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
15440 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
15450 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
15460 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
15470 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
15480 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15490 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
154a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
154b0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
154c0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
154d0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
154e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
154f0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
15500 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15510 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15520 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
15530 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15540 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15550 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
15560 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
15570 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
15580 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
15590 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
155a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
155b0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
155c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
155d0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
155e0 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
155f0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
15600 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15610 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
15620 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
15630 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
15640 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
15650 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
15660 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
15670 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
15680 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
15690 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
156a0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
156b0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
156c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
156d0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
156e0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
156f0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
15700 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
15710 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
15720 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
15730 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
15740 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15750 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
15760 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
15770 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
15780 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
15790 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
157a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
157b0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
157c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
157d0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
157e0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
157f0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
15800 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
15810 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
15820 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
15830 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15840 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
15850 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
15860 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
15870 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
15880 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
15890 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48  C library..** {H
158a0 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
158b0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
158c0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
158d0 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
158e0 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
158f0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15900 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
15910 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
15920 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
15930 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
15940 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
15950 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
15960 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
15970 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
15980 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
15990 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
159a0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
159b0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
159c0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
159d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
159e0 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
159f0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
15a00 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
15a10 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
15a20 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
15a30 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
15a40 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
15a50 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
15a60 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
15a70 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
15a80 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
15a90 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
15aa0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
15ab0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
15ac0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
15ad0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
15ae0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
15af0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
15b00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
15b10 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
15b20 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
15b30 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
15b40 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
15b50 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
15b60 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
15b70 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
15b80 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
15b90 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
15ba0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
15bb0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
15bc0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
15bd0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
15be0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
15bf0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
15c00 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
15c10 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
15c20 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
15c30 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
15c40 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
15c50 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
15c60 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
15c70 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
15c80 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
15c90 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
15ca0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15cb0 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65  ** {H17303}  The
15cc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15cd0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
15ce0 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
15cf0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
15d00 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20          a newly 
15d10 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63  checked-out bloc
15d20 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  k of at least N 
15d30 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  bytes of memory.
15d40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
15d50 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
15d60 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72  ned, or it retur
15d70 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73  ns NULL if it is
15d80 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20   unable.**      
15d90 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20       to fulfill 
15da0 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a  the request..**.
15db0 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65  ** {H17304}  The
15dc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15dd0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
15de0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
15df0 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20  inter if.**     
15e00 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20        N is less 
15e10 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
15e20 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   zero..**.** {H1
15e30 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69  7305}  The [sqli
15e40 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74  te3_free(P)] int
15e50 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20  erface releases 
15e60 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c  memory previousl
15e70 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  y.**           r
15e80 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
15e90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
15ea0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
15eb0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
15ec0 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61       making it a
15ed0 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75  vailable for reu
15ee0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30  se..**.** {H1730
15ef0 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  6}  A call to [s
15f00 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c  qlite3_free(NULL
15f10 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  )] is a harmless
15f20 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48   no-op..**.** {H
15f30 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74  17310}  A call t
15f40 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
15f50 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69  oc(0,N)] is equi
15f60 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
15f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
15f80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15f90 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  (N)]..**.** {H17
15fa0 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  312}  A call to 
15fb0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15fc0 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
15fd0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
15fe0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
15ff0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
16000 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d  ..**.** {H17315}
16010 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
16020 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  e uses [sqlite3_
16030 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
16040 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
16050 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64  **           and
16060 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16070 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  ] for all of its
16080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16090 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
160a0 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e      deallocation
160b0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   needs..**.** {H
160c0 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
160d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
160e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
160f0 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
16100 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
16110 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66     to a block of
16120 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d   checked-out mem
16130 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
16140 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a  N bytes in size.
16150 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
16160 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
16170 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ned, or a NULL p
16180 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
16190 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71  17321}  When [sq
161a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
161b0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
161c0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
161d0 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
161e0 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65        copies the
161f0 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f   first K bytes o
16200 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50  f content from P
16210 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a   into the newly.
16220 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c  **           all
16230 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68  ocated block, wh
16240 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73  ere K is the les
16250 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65  ser of N and the
16260 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20   size of.**     
16270 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72        the buffer
16280 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32   P..**.** {H1732
16290 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  2}  When [sqlite
162a0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
162b0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
162c0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
162d0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
162e0 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62    releases the b
162f0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
16300 48 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73  H17323}  When [s
16310 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
16320 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c  ,N)] returns NUL
16330 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20  L, the buffer P 
16340 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  is.**           
16350 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20  not modified or 
16360 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
16370 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
16380 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65  ** {A17350}  The
16390 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
163a0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
163b0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
163c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
163d0 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  *           must
163e0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
163f0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
16400 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
16410 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
16420 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f      invocation o
16430 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
16440 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16450 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
16460 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
16470 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20     not yet been 
16480 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
16490 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20 61 70  {A17351}  The ap
164a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
164b0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
164c0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
164d0 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63            a bloc
164e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
164f0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
16500 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
16510 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16520 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
16530 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16540 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
16550 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
16560 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
16570 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
16580 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
16590 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
165a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
165b0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
165c0 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33  Statistics {H173
165d0 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a  70} <S30210>.**.
165e0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
165f0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
16600 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
16610 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
16620 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
16630 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16640 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
16650 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
16660 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
16670 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
16680 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
16690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
166a0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
166b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
166c0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54  **.** {H17371} T
166d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
166e0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
166f0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
16700 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
16710 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65  *          of me
16720 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
16730 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
16740 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
16750 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  ed)..**.** {H173
16760 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
16770 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
16780 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
16790 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
167a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
167b0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
167c0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
167d0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
167e0 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20  er mark.**      
167f0 20 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73      was last res
16800 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  et..**.** {H1737
16810 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65  4} The values re
16820 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16830 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16840 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
16850 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
16860 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
16870 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
16880 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ead.**          
16890 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
168a0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
168b0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
168c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
168d0 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74           but not
168e0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
168f0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
16900 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
16910 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  rary.**         
16920 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
16930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16940 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
16950 2a 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d  * {H17375} The m
16960 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
16970 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
16980 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
16990 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
169a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
169b0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
169c0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
169d0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
169e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
169f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16a00 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68  ()] is true.  Th
16a10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
16a30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16a40 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
16a50 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
16a60 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  mark.**         
16a70 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
16a80 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
16a90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
16aa0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
16ab0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
16ac0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16ad0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
16ae0 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
16af0 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
16b00 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
16b10 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d  nerator {H17390}
16b20 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
16b30 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
16b40 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
16b50 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
16b60 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
16b70 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
16b80 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f  select random RO
16b90 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74  WIDs when insert
16ba0 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
16bb0 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
16bc0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
16bd0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
16be0 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54  ssible ROWID.  T
16bf0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
16c00 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
16c10 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
16c20 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
16c30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
16c40 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
16c50 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
16c60 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
16c70 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
16c80 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
16c90 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
16ca0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
16cb0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
16cc0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
16cd0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
16ce0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
16cf0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
16d00 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
16d10 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
16d20 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
16d30 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
16d40 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
16d50 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
16d60 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
16d70 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
16d80 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
16d90 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
16da0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
16db0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
16dc0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
16dd0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
16de0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
16df0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
16e00 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
16e10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16e20 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
16e30 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
16e40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
16e50 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68  *.** {H17392} Th
16e60 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  e [sqlite3_rando
16e70 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65  mness(N,P)] inte
16e80 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
16e90 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
16ea0 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79      high-quality
16eb0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
16ec0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
16ed0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
16ee0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
16ef0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
16f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
16f10 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
16f20 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
16f30 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37  cks {H12500} <S7
16f40 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0100>.**.** This
16f50 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
16f60 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
16f70 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
16f80 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
16f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16fa0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
16fb0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16fc0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
16fd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16fe0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
16ff0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
17000 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
17010 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
17020 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
17030 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
17040 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
17050 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
17060 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
17070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
17080 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
17090 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
170a0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
170b0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
170c0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
170d0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
170e0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
170f0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
17100 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17110 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
17120 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
17130 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
17140 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
17150 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
17160 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
17170 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
17180 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
17190 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
171a0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
171b0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
171c0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
171d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
171e0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
171f0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
17200 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
17210 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
17220 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
17230 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
17240 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
17250 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
17260 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
17270 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
17280 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
17290 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
172a0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
172b0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
172c0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
172d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
172e0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
172f0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
17300 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
17310 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
17320 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
17330 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
17340 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17350 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
17360 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
17370 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
17380 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
17390 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
173a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
173b0 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
173c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
173d0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
173e0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
173f0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
17400 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
17410 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
17420 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
17430 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
17440 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49  ss is denied.  I
17450 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
17460 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
17470 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
17480 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17490 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
174a0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
174b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
174c0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
174d0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
174e0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
174f0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
17500 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
17510 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
17520 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
17530 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
17540 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
17550 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
17560 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
17570 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
17580 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
17590 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
175a0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
175b0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
175c0 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   table..**.** Th
175d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
175e0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
175f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17600 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
17610 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
17620 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
17630 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17640 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20   interface. The 
17650 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17660 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
17670 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17680 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
17690 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
176a0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
176b0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
176c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
176d0 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72  orized. The thir
176e0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
176f0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
17700 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
17710 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
17720 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
17730 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
17740 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
17750 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
17760 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
17770 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
17780 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
17790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
177a0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
177b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
177c0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
177d0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
177e0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
177f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
17800 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
17810 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
17820 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
17830 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
17840 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
17850 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
17860 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
17870 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
17880 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
17890 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
178a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
178b0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
178c0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
178d0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
178e0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
178f0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
17900 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
17910 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
17920 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
17930 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
17940 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
17950 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
17960 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
17970 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
17980 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
17990 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
179a0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
179b0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
179c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
179d0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
179e0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
179f0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
17a00 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
17a10 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
17a20 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
17a30 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
17a40 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
17a50 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
17a60 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
17a70 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
17a80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
17a90 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
17aa0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
17ab0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
17ac0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
17ad0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
17ae0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
17af0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
17b00 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
17b10 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
17b20 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
17b30 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
17b40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
17b50 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
17b60 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
17b70 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
17b80 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
17b90 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
17ba0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
17bb0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
17bc0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
17bd0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
17be0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
17bf0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
17c00 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
17c10 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
17c20 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
17c30 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
17c40 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
17c50 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
17c60 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
17c70 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
17c80 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
17c90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17ca0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
17cb0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
17cc0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
17cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17ce0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
17cf0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
17d00 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
17d10 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
17d20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17d30 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
17d40 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
17d50 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
17d60 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
17d70 65 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  eprepared during
17d80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17d90 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
17da0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
17db0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
17dc0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
17dd0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
17de0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
17df0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
17e00 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
17e10 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
17e20 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
17e30 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
17e40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17e50 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
17e60 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
17e70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
17e80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
17e90 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
17ea0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
17eb0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
17ec0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
17ed0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
17ee0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
17ef0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
17f00 32 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2501} The [sqlit
17f10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17f20 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  r(D,...)] interf
17f30 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a  ace registers a.
17f40 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
17f50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17f60 77 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f  with database co
17f70 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
17f80 2a 20 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61  * {H12502} The a
17f90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17fa0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
17fb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17fc0 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
17fd0 62 65 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e  being parseed an
17fe0 64 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  d compiled..**.*
17ff0 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68  * {H12503} If th
18000 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18010 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
18020 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
18030 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
18040 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
18050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
18060 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
18070 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
18080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
18090 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74  interface call t
180a0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20  hat caused.**   
180b0 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f         the autho
180c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74  rizer callback t
180d0 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c  o run shall fail
180e0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
180f0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
18100 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  OR] error code a
18110 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
18120 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
18130 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20  .**.** {H12504} 
18140 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
18150 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
18160 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
18170 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  , the operation.
18180 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63  **          desc
18190 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73  ribed is process
181a0 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a  ed normally..**.
181b0 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e  ** {H12505} When
181c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
181d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
181e0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
181f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
18200 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65  application inte
18210 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20  rface call that 
18220 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20  caused the.**   
18230 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
18240 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
18250 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20  n shall fail.** 
18260 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e           with an
18270 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
18280 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
18290 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  n error message.
182a0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c  **          expl
182b0 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65  aining that acce
182c0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a  ss is denied..**
182d0 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20  .** {H12506} If 
182e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
182f0 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
18300 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
18310 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
18320 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
18330 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  s [SQLITE_READ] 
18340 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  and the authoriz
18350 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
18360 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
18370 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
18380 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   then the prepar
18390 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
183a0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a  constructed to.*
183b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72  *          inser
183c0 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  t a NULL value i
183d0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
183e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
183f0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20   would have.**  
18400 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61          been rea
18410 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
18420 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
18430 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
18440 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  7} If the author
18450 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
18460 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
18470 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
18480 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
18490 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67  ack) is anything
184a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
184b0 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a  ITE_READ], then.
184c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
184d0 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  turn of [SQLITE_
184e0 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20  IGNORE] has the 
184f0 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b  same effect as [
18500 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a  SQLITE_DENY]..**
18510 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65  .** {H12510} The
18520 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18530 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
18540 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
18550 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
18560 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70       the third p
18570 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18580 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18590 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
185a0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  face..**.** {H12
185b0 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  511} The second 
185c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
185d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
185e0 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
185f0 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
18600 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
18610 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
18620 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
18630 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
18640 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
18650 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32  d..**.** {H12512
18660 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
18670 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
18680 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
18690 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20  back are.**     
186a0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
186b0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
186c0 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20  t contain.**    
186d0 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c        additional
186e0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
186f0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
18700 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
18710 2a 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20  * {H12520} Each 
18720 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
18730 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
18740 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20  )] overrides.** 
18750 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65           any pre
18760 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65  viously installe
18770 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  d authorizer..**
18780 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e  .** {H12521} A N
18790 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
187a0 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
187b0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20  horization.**   
187c0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
187d0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
187e0 2a 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64  * {H12522} The d
187f0 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65  efault authorize
18800 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  r is NULL..*/.in
18810 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
18820 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
18830 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
18840 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
18850 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
18860 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18870 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
18880 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
18890 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
188a0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
188b0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
188c0 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e  H12590} <H12500>
188d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
188e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
188f0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
18900 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18910 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
18920 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
18930 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
18940 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
18950 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
18960 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
18970 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
18980 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
18990 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
189a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
189b0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
189c0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
189d0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
189e0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
189f0 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
18a00 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
18a10 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
18a20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
18a30 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
18a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
18a50 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
18a60 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
18a70 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
18a80 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
18a90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18aa0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
18ab0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30  on Codes {H12550
18ac0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
18ad0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
18ae0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
18af0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
18b00 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
18b10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
18b20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
18b30 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
18b40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
18b50 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
18b60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18b70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
18b80 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
18b90 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
18ba0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
18bb0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
18bc0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
18bd0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
18be0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
18bf0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
18c00 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
18c10 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
18c20 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
18c30 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
18c40 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
18c50 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
18c60 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
18c70 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
18c80 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
18c90 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
18ca0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
18cb0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
18cc0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
18cd0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
18ce0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
18cf0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
18d00 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18d10 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
18d20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18d30 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
18d40 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
18d50 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
18d60 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
18d70 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
18d80 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
18d90 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
18da0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
18db0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
18dc0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18dd0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18de0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18df0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18e00 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
18e10 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
18e20 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
18e30 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
18e40 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
18e50 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
18e60 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
18e70 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d  :.**.** {H12551}
18e80 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18e90 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20  meter to an.**  
18ea0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18eb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18ec0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18ed0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
18ee0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
18ef0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
18f00 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
18f10 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
18f20 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f  ifies what actio
18f30 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
18f40 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
18f50 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32  d..**.** {H12552
18f60 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74  } The 3rd and 4t
18f70 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
18f80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
18f90 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18fa0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
18fb0 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
18fc0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
18fd0 61 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  all be parameter
18fe0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
18ff0 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  ing on which.** 
19000 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19010 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
19020 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64  er code] is used
19030 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
19040 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
19050 7b 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68  {H12553} The 5th
19060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
19070 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
19080 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
19090 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
190a0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61  er callback] sha
190b0 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a  ll be the name.*
190c0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
190d0 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d  e database (exam
190e0 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65  ple: "main", "te
190f0 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70  mp", etc.) if ap
19100 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  plicable..**.** 
19110 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68  {H12554} The 6th
19120 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
19130 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
19140 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
19150 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
19160 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61  er callback] sha
19170 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a  ll be the name.*
19180 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
19190 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
191a0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
191b0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
191c0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
191d0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
191e0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
191f0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
19200 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
19210 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
19220 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
19230 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
19240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19260 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
19270 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
19280 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
19290 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
192a0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
192b0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
192c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
192d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
192e0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
192f0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
19300 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19310 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19330 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
19340 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
19350 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
19360 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19380 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
19390 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
193a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
193b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
193c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
193d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
193e0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
193f0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19400 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19420 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
19430 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
19440 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19450 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19470 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
19480 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
19490 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
194a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
194b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
194c0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
194d0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
194e0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
194f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19500 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
19510 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
19520 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
19530 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19540 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19550 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19560 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
19570 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
19580 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19590 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
195a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
195b0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
195c0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
195d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
195e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
195f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19600 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
19610 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
19620 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
19630 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19640 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
19650 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
19660 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19670 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19680 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19690 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
196a0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
196b0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
196c0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
196d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
196e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
196f0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
19700 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19710 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19720 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19730 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
19740 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
19750 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
19760 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19770 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19780 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
19790 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
197a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
197b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
197c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
197d0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
197e0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
197f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19800 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19810 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19820 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
19830 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
19840 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
19850 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
19860 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19870 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
19880 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
19890 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
198a0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
198b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
198c0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
198d0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
198e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
198f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19910 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
19920 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c       22   /* NUL
19930 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
19940 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19950 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
19960 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
19970 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
19980 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
19990 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
199a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
199b0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
199c0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
199d0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
199e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
199f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
19a00 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
19a10 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
19a20 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
19a30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
19a50 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
19a60 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
19a70 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
19a80 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19a90 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
19aa0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
19ab0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
19ac0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19ad0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19ae0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
19af0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
19b00 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
19b10 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19b20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19b30 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19b40 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
19b50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
19b60 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
19b70 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
19b80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
19b90 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
19ba0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19bb0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
19bc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19bd0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
19be0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
19bf0 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d   /* Function Nam
19c00 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
19c10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19c20 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
19c30 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
19c40 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
19c50 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
19c60 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
19c70 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
19c80 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c  tions {H12280} <
19c90 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S60400>.** EXPER
19ca0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
19cb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
19cc0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
19cd0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
19ce0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
19cf0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
19d00 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
19d10 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
19d20 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
19d30 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19d40 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19d50 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
19d60 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
19d70 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
19d80 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
19d90 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
19da0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
19db0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
19dc0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19dd0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19de0 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
19df0 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
19e00 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19e10 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19e20 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
19e30 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
19e40 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
19e50 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
19e60 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
19e70 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
19e80 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
19e90 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
19ea0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
19eb0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
19ec0 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  trigger..**.** T
19ed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
19ee0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
19ef0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
19f00 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
19f10 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
19f20 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19f30 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
19f40 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
19f50 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
19f60 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
19f70 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
19f80 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
19f90 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
19fa0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
19fb0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
19fc0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
19fd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20  .**.** {H12281} 
19fe0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
19ff0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1a000 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   by [sqlite3_tra
1a010 63 65 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20  ce()] .**       
1a020 20 20 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f     shall be invo
1a030 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ked.**          
1a040 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20  whenever an SQL 
1a050 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1a060 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74  begins to execut
1a070 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
1a080 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69    whenever a tri
1a090 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20  gger subprogram 
1a0a0 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
1a0b0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  run..**.** {H122
1a0c0 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  82} Each call to
1a0d0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
1a0e0 29 5d 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64  )] shall overrid
1a0f0 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79  e the previously
1a100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
1a110 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61  istered trace ca
1a120 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  llback..**.** {H
1a130 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72  12283} A NULL tr
1a140 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61  ace callback sha
1a150 6c 6c 20 64 69 73 61 62 6c 65 20 74 72 61 63 69  ll disable traci
1a160 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  ng..**.** {H1228
1a170 34 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67  4} The first arg
1a180 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
1a190 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c  ce callback shal
1a1a0 6c 20 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a  l be a copy of.*
1a1b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70  *          the p
1a1c0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
1a1d0 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
1a1e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
1a1f0 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ace()]..**.** {H
1a200 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e  12285} The secon
1a210 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
1a220 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
1a230 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
1a240 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1a250 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
1a260 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72  ontaining the or
1a270 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20  iginal text.**  
1a280 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53          of the S
1a290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1a2a0 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e  it was passed in
1a2b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1a2c0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
1a2d0 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
1a2e0 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53  ivalent, or an S
1a2f0 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63  QL comment indic
1a300 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e  ating the beginn
1a310 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1a320 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62  of a trigger sub
1a330 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
1a340 48 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c  H12287} The call
1a350 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1a360 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c  gistered by [sql
1a370 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
1a380 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20  is invoked.**   
1a390 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53         as each S
1a3a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1a3b0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ishes..**.** {H1
1a3c0 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20  2288} The first 
1a3d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a3e0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1a3f0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
1a400 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33  *          the 3
1a410 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1a420 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
1a430 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ()]..**.** {H122
1a440 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  89} The second p
1a450 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a460 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1a470 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
1a480 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1a490 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  d UTF-8 string t
1a4a0 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  hat contains the
1a4b0 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f   complete text o
1a4c0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1a4d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1a4e0 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73  as it was proces
1a4f0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1a500 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
1a510 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
1a520 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a   equivalent..**.
1a530 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20  ** {H12290} The 
1a540 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1a550 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
1a560 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73  allback is an es
1a570 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20  timate.**       
1a580 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72     of the number
1a590 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20   of nanoseconds 
1a5a0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1a5b0 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a  me required to.*
1a5c0 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74  *          run t
1a5d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1a5e0 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66   from start to f
1a5f0 69 6e 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45  inish..*/.SQLITE
1a600 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1a610 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
1a620 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
1a630 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
1a640 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
1a650 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
1a660 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1a670 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1a680 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1a690 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1a6a0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1a6b0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1a6c0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1a6d0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1a6e0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1a6f0 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34  s {H12910} <S604
1a700 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
1a710 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
1a720 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1a730 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70  ction - the.** p
1a740 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1a750 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b   - that is invok
1a760 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1a770 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72  during long.** r
1a780 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  unning calls to 
1a790 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1a7a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1a7b0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a7c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e  e3_get_table()].
1a7d0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1a7e0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1a7f0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1a800 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1a810 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1a820 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uery..**.** If t
1a830 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1a840 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1a850 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1a860 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1a870 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1a880 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1a890 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1a8a0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1a8b0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1a8c0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1a8d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1a8e0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73  ress handler mus
1a8f0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1a900 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1a910 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1a920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1a930 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1a940 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1a950 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1a960 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a970 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1a980 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1a990 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1a9a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a9b0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1a9c0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1a9d0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1a9e0 68 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  h..**.** INVARIA
1a9f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  NTS:.**.** {H129
1aa00 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  11} The callback
1aa10 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1aa20 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1aa30 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1aa40 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ().**          i
1aa50 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
1aa60 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1aa70 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1aa80 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1aa90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1aaa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d  ..**.** {H12912}
1aab0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
1aac0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1aad0 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79  d once for every
1aae0 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20   N virtual.**   
1aaf0 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f         machine o
1ab00 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20  pcodes, where N 
1ab10 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
1ab20 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
1ab30 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
1ab40 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1ab50 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  ler()] call that
1ab60 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
1ab70 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c          the call
1ab80 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c  back.  If N is l
1ab90 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69  ess than 1, sqli
1aba0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1abb0 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20  dler().**       
1abc0 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20     acts as if a 
1abd0 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61  NULL progress ha
1abe0 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73  ndler had been s
1abf0 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  pecified..**.** 
1ac00 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {H12913} The pro
1ac10 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
1ac20 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
1ac30 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
1ac40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
1ac50 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ac60 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1ac70 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  r()..**.** {H129
1ac80 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61  14} The fourth a
1ac90 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1aca0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1acb0 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20  ler() is a.**   
1acc0 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e         void poin
1acd0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
1ace0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1acf0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
1ad00 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69  function each ti
1ad10 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  me it is invoked
1ad20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d  ..**.** {H12915}
1ad30 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
1ad40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
1ad50 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20  esults in fewer 
1ad60 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a  than N opcodes.*
1ad70 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67  *          being
1ad80 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20   executed, then 
1ad90 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1ada0 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69  lback is never i
1adb0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1adc0 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c  12916} Every cal
1add0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
1ade0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1adf0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  ].**          ov
1ae00 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65  erwrites any pre
1ae10 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
1ae20 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ed progress hand
1ae30 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ler..**.** {H129
1ae40 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  17} If the progr
1ae50 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
1ae60 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65  back is NULL the
1ae70 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a  n no progress.**
1ae80 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65            handle
1ae90 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  r is invoked..**
1aea0 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20  .** {H12918} If 
1aeb0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1aec0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
1aed0 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61  result other tha
1aee0 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  n 0, then.**    
1aef0 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69        the behavi
1af00 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69  or is a if [sqli
1af10 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
1af20 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64   had been called
1af30 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53  ..**          <S
1af40 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73  30500>.*/.void s
1af50 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1af60 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1af70 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1af80 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1af90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1afa0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1afb0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1afc0 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30   {H12700} <S4020
1afd0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
1afe0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1aff0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1b000 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
1b010 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
1b020 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1b030 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61  ment. The filena
1b040 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1b050 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1b060 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1b070 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1b080 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1b090 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1b0a0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1b0b0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1b0c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1b0d0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1b0e0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1b0f0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1b100 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1b110 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1b120 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1b130 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1b140 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1b150 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1b160 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1b170 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1b180 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1b190 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1b1a0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1b1b0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1b1c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1b1d0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1b1e0 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  t. If the databa
1b1f0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1b200 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1b210 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1b220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1b230 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1b240 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1b250 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1b260 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ned.  The.** [sq
1b270 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1b280 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1b290 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
1b2a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1b2b0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
1b2c0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
1b2d0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
1b2e0 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
1b2f0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1b300 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1b310 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1b320 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1b330 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1b340 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1b350 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1b360 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1b370 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1b380 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1b390 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1b3a0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1b3b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1b3c0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1b3d0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1b3e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1b3f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1b400 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1b410 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1b420 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1b430 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1b440 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1b450 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1b460 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1b470 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1b480 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1b490 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1b4a0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1b4b0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1b4c0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1b4d0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1b4e0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1b4f0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1b500 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1b510 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
1b520 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
1b530 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1b540 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1b550 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1b560 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1b570 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1b580 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b590 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
1b5a0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1b5b0 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ags:.**.** <dl>.
1b5c0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
1b5d0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1b5e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1b5f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1b600 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1b610 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1b620 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1b630 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1b640 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1b650 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
1b660 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
1b670 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1b680 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1b690 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1b6a0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1b6b0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1b6c0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1b6d0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1b6e0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1b6f0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1b700 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1b710 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1b720 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1b730 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1b740 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1b750 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1b760 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
1b770 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1b780 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1b790 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1b7a0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1b7b0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1b7c0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1b7d0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1b7e0 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
1b7f0 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
1b800 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
1b810 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
1b820 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
1b830 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
1b840 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1b850 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1b860 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  16().</dd>.** </
1b870 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1b880 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1b890 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1b8a0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1b8b0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1b8c0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1b8d0 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
1b8e0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1b8f0 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
1b900 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
1b910 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1b920 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
1b930 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1b940 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  lags,.** then th
1b950 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
1b960 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
1b970 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1b980 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1b990 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1b9a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b9b0 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1b9c0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1b9d0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1b9e0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1b9f0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1ba00 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1ba10 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1ba20 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1ba30 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65  rt-time.  If the
1ba40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1ba50 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1ba60 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1ba70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ba80 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1ba90 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1baa0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1bab0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1bac0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1bad0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1bae0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1baf0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1bb00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1bb10 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1bb20 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1bb30 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1bb40 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1bb50 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1bb60 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1bb70 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
1bb80 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1bb90 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1bba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1bbb0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1bbc0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1bbd0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1bbe0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1bbf0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1bc00 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1bc10 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1bc20 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1bc30 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1bc40 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1bc50 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1bc60 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1bc70 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1bc80 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1bc90 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1bca0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1bcb0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1bcc0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1bcd0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1bce0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
1bcf0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1bd00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1bd10 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1bd20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1bd30 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1bd40 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1bd50 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1bd60 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1bd70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1bd80 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1bd90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1bda0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1bdb0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
1bdc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bdd0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1bde0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1bdf0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1be00 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1be10 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1be20 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1be30 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1be40 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1be50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1be60 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
1be70 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1be80 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1be90 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1bea0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1beb0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1bec0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1bed0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1bee0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1bef0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1bf00 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1bf10 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1bf20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1bf30 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1bf40 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1bf50 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1bf60 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1bf70 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1bf80 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1bf90 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1bfa0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1bfb0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1bfc0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1bfd0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1bfe0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1bff0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1c000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c010 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1c020 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  NTS:.**.** {H127
1c030 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1c040 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1c050 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1c060 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1c070 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1c080 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
1c090 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
1c0a0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1c0b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
1c0c0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
1c0d0 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
1c0e0 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
1c0f0 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
1c100 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1c110 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {H12702} The fil
1c120 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1c130 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1c140 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
1c150 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
1c160 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
1c170 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1c180 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
1c190 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
1c1a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c1b0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
1c1c0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1c1d0 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63   {H12703} A succ
1c1e0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1c1f0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
1c200 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1c210 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1c220 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1c230 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
1c240 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
1c250 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1c260 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1c270 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
1c280 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ppDb..**.** {H12
1c290 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
1c2a0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1c2b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1c2c0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1c2d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c2e0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
1c2f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1c300 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1c310 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1c320 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1c330 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1c340 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lure..**.** {H12
1c350 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1c360 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1c370 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1c380 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1c390 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1c3a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1c3b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c3c0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1c3d0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37  8..**.** {H12707
1c3e0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1c3f0 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1c400 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1c410 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1c420 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c430 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1c440 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1c450 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b  * {H12709} The [
1c460 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1c470 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1c480 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1c490 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c4a0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1c4b0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1c4c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1c4d0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1c4e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c4f0 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1c500 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  REATE]..**.** {H
1c510 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1c520 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1c530 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1c540 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1c550 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1c560 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1c570 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1c580 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1c590 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1c5a0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1c5b0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1c5c0 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68  * {H12712} If th
1c5d0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1c5e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c5f0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1c600 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1c610 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1c620 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c630 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1c640 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c650 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1c660 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1c670 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1c680 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1c690 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1c6a0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1c6b0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1c6c0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1c6d0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  system..**.** {H
1c6e0 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1c6f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1c700 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1c710 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1c720 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1c730 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1c740 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1c750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1c760 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1c770 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1c780 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1c790 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1c7a0 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65   {H12714} If the
1c7b0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1c7c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c7d0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1c7e0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1c7f0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1c800 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1c810 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1c820 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1c830 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1c840 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1c850 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1c860 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1c870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1c880 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1c890 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  base..**.** {H12
1c8a0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1c8b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1c8c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1c8d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1c8e0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1c8f0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1c900 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1c910 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1c920 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1c930 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1c940 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1c950 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1c960 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1c970 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1c980 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1c990 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1c9a0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c9b0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1c9c0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1c9d0 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1c9e0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39  o>.**.** {H12719
1c9f0 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1ca00 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1ca10 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1ca20 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1ca30 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1ca40 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1ca50 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1ca60 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1ca70 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1ca80 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1ca90 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1caa0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1cab0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1cac0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1cad0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  todo>.**.** {H12
1cae0 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1caf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1cb00 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1cb10 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1cb20 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1cb30 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1cb40 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1cb50 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1cb60 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1cb70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1cb80 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1cb90 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1cba0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1cbb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1cbc0 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {H12723} Two [da
1cbd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cbe0 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1cbf0 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1cc00 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1cc10 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1cc20 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1cc30 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1cc40 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1cc50 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1cc60 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1cc70 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1cc80 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1cc90 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1cca0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1ccb0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1ccc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1ccd0 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1cce0 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1ccf0 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1cd00 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1cd10 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1cd20 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1cd30 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1cd40 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1cd50 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1cd60 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1cd70 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1cd80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1cd90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1cda0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1cdb0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1cdc0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1cdd0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1cde0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1cdf0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ce00 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ce10 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1ce20 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ce30 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ce40 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ce50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ce60 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1ce70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ce80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1ce90 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1cea0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1ceb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1cec0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1ced0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1cee0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1cef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1cf00 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1cf10 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20  ssages {H12800} 
1cf20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60200>.**.** T
1cf30 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
1cf40 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
1cf50 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1cf60 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
1cf70 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1cf80 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1cf90 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1cfa0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
1cfb0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
1cfc0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1cfd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1cfe0 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
1cff0 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
1d000 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
1d010 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
1d020 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
1d030 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1d040 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
1d050 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
1d060 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
1d070 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1d080 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1d090 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1d0a0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1d0b0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1d0c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1d0d0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1d0e0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1d0f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
1d100 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1d110 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1d120 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1d130 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1d140 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1d150 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1d160 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1d170 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1d180 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1d190 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1d1a0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1d1b0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1d1c0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1d1d0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1d1e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1d1f0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ce functions..**
1d200 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1d210 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1d220 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1d230 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1d240 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1d250 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1d260 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1d270 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1d280 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1d290 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1d2a0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1d2b0 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  t be set..**.** 
1d2c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1d2d0 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b  * {H12801} The [
1d2e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d2f0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
1d300 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1d310 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72  c.**          [r
1d320 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
1d330 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1d340 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1d350 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20  st recently.**  
1d360 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69          failed i
1d370 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73  nterface call as
1d380 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1d390 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1d3a0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
1d3b0 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73   {H12803} The [s
1d3c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29  qlite3_errmsg(D)
1d3d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1d3e0 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20  rrmsg16(D)].**  
1d3f0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
1d400 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  es return Englis
1d410 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20  h-language text 
1d420 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a  that describes.*
1d430 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65  *          the e
1d440 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74  rror in the most
1d450 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c  ly recently fail
1d460 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1d470 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  l,.**          e
1d480 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72  ncoded as either
1d490 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1d4a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1d4b0 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68  *.** {H12807} Th
1d4c0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1d4d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
1d4e0 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71  rrmsg()] and [sq
1d4f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1d500 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
1d510 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
1d520 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e  e next SQLite in
1d530 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a  terface call..**
1d540 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c  .** {H12808} Cal
1d550 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
1d560 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
1d570 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63  eturn an error c
1d580 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
1d590 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
1d5a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
1d5b0 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  ) do not.**     
1d5c0 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20       change the 
1d5d0 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65  error code or me
1d5e0 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62  ssage returned b
1d5f0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1d600 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1d610 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1d620 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1d630 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1d640 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49  **.** {H12809} I
1d650 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
1d660 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65  re not associate
1d670 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  d with a specifi
1d680 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  c.**          [d
1d690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d6a0 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  on] (examples:.*
1d6b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1d6c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f  te3_mprintf()] o
1d6d0 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  r [sqlite3_enabl
1d6e0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1d6f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f  ].**          do
1d700 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1d710 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1d720 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1d730 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d740 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
1d750 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
1d760 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
1d770 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d780 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1d790 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1d7a0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1d7b0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1d7c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1d7d0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1d7e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d7f0 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1d800 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1d810 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1d820 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1d830 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1d840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d850 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1d860 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1d870 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1d880 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1d890 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1d8a0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1d8b0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1d8c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d8d0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1d8e0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1d8f0 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1d900 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1d910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1d920 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1d930 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1d940 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1d950 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1d960 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1d970 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1d980 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d990 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1d9a0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1d9b0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1d9c0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1d9d0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1d9e0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1d9f0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1da00 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1da10 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1da20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1da30 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1da40 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1da50 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1da60 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1da70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1da80 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1da90 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1daa0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1dab0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1dac0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1dad0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1dae0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1daf0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1db00 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1db10 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1db20 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1db30 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1db40 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1db50 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1db60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1db70 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1db80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1db90 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1dba0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1dbb0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1dbc0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1dbd0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1dbe0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1dbf0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1dc00 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1dc10 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1dc20 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1dc30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1dc40 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1dc50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1dc60 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1dc70 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1dc80 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1dc90 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1dca0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1dcb0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1dcc0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1dcd0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1dce0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1dcf0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1dd00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1dd10 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1dd20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1dd30 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1dd40 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1dd50 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1dd60 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1dd70 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1dd80 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1dd90 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1dda0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1ddb0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1ddc0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1ddd0 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a   a hard upper.**
1dde0 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20   bound set by a 
1ddf0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70  compile-time C p
1de00 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1de10 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d  o named SQLITE_M
1de20 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20  AX_XYZ..** (The 
1de30 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1de40 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1de50 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
1de60 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
1de70 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1de80 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1de90 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1dea0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1deb0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1dec0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
1ded0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
1dee0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1def0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1df00 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1df10 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1df20 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1df30 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1df40 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1df50 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1df60 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1df70 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1df80 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1df90 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1dfa0 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72   a.** webbrowser
1dfb0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
1dfc0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
1dfd0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
1dfe0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
1dff0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
1e000 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
1e010 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
1e020 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
1e030 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
1e040 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
1e050 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
1e060 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
1e070 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
1e080 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
1e090 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
1e0a0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
1e0b0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
1e0c0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
1e0d0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
1e0e0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
1e0f0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
1e100 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
1e110 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
1e120 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1e130 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e140 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
1e150 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
1e160 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
1e170 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
1e180 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1e190 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
1e1a0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
1e1b0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
1e1c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
1e1d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1e1e0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
1e1f0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
1e200 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
1e210 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
1e220 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
1e230 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1e240 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73  .** {H12762} A s
1e250 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1e260 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1e270 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1e280 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
1e290 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73  positive changes
1e2a0 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
1e2b0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
1e2c0 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
1e2d0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1e2e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1e2f0 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f   to the lesser o
1e300 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
1e310 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20   upper.**       
1e320 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20     bound on the 
1e330 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69  size of C that i
1e340 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
1e350 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  -time..**.** {H1
1e360 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
1e370 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1e380 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1e390 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
1e3a0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
1e3b0 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
1e3c0 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  te of the [datab
1e3d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e3e0 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  D unchanged..**.
1e3f0 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75  ** {H12769} A su
1e400 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1e410 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1e420 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20  D,C,V)] returns 
1e430 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e440 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
1e450 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1e460 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1e470 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1e490 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77  ction] D as it w
1e4a0 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  as prior to the 
1e4b0 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  call..*/.int sql
1e4c0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1e4d0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1e4e0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1e4f0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1e500 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1e510 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48  ries {H12790} <H
1e520 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  12760>.** KEYWOR
1e530 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
1e540 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65  ory} {limit cate
1e550 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
1e560 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
1e570 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70  fine various asp
1e580 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62  ects of a [datab
1e590 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
1e5a0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
1e5b0 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62  imited in size b
1e5c0 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  y calls to [sqli
1e5d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1e5e0 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   The meanings of
1e5f0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1e600 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  its are as follo
1e610 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ws:.**.** <dl>.*
1e620 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e630 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1e640 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e650 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1e660 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1e670 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
1e680 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e690 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1e6a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e6b0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1e6c0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
1e6d0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1e6e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e6f0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1e700 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e710 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1e720 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1e730 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1e740 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1e750 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74  of a SELECT or t
1e760 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e770 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1e780 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
1e790 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
1e7a0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
1e7b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1e7c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1e7d0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1e7e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e7f0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1e800 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1e810 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1e820 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e830 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1e840 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1e850 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e860 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1e870 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1e880 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1e890 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e8a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1e8b0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1e8c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e8d0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1e8e0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1e8f0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1e900 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1e910 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1e920 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1e930 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e940 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
1e950 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e960 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e970 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
1e980 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
1e990 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e9a0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1e9b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e9c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e9d0 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  f attached datab
1e9e0 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ases.</dd>.**.**
1e9f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1ea00 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1ea10 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1ea20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1ea30 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1ea40 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1ea50 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47  the LIKE or.** G
1ea60 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  LOB operators.</
1ea70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1ea80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ea90 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1eaa0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1eab0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1eac0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1ead0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1eae0 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1eaf0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1eb00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eb10 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
1eb20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb30 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
1eb40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1eb50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1eb60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1eb70 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
1eb80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1eba0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1ebb0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1ebc0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1ebd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1ebe0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
1ebf0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1ec00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1ec10 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
1ec20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
1ec30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1ec40 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
1ec50 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
1ec60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
1ec70 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
1ec80 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
1ec90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1eca0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1ecb0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
1ecc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1ecd0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1ece0 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
1ecf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1ed00 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
1ed10 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
1ed20 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
1ed30 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1ed40 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1ed50 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1ed60 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1ed70 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1ed80 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1ed90 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1eda0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1edb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1edc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1edd0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1ede0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1edf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1ee00 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1ee10 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73  prior call to [s
1ee20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1ee30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1ee40 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ee50 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1ee60 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1ee70 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
1ee80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
1ee90 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
1eea0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
1eeb0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1eec0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
1eed0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
1eee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1eef0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
1ef00 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
1ef10 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1ef20 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
1ef30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ef40 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
1ef50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
1ef60 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1ef70 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1ef80 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1ef90 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
1efa0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1efb0 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73  tor. If nByte is
1efc0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1efd0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1efe0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
1eff0 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
1f000 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
1f010 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1f020 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
1f030 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
1f040 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
1f050 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
1f060 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
1f070 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
1f080 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
1f090 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
1f0a0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
1f0b0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
1f0c0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
1f0d0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
1f0e0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
1f0f0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1f100 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1f110 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
1f120 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1f130 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1f140 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
1f150 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1f160 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
1f170 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
1f180 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
1f190 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1f1a0 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a  bytes..**.** *pz
1f1b0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1f1c0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1f1d0 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
1f1e0 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66   end of the.** f
1f1f0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1f200 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1f210 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1f220 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
1f230 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
1f240 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1f250 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1f260 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
1f270 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
1f280 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
1f290 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
1f2a0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
1f2b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f2c0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
1f2d0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
1f2e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1f2f0 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20  p()].  If there 
1f300 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1f310 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1f320 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20  o NULL.  If the 
1f330 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1f340 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1f350 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1f360 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1f370 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1f380 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1f390 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31   to NULL..** {A1
1f3a0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
1f3b0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1f3c0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1f3d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1f3e0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1f3f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1f400 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1f410 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1f420 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1f430 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
1f440 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
1f450 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
1f460 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1f470 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1f480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1f490 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f4a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1f4b0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1f4c0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1f4d0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1f4e0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1f4f0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1f500 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1f510 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1f520 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f530 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1f540 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1f550 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
1f560 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1f570 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1f580 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1f590 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1f5a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1f5b0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1f5c0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1f5d0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1f5e0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1f5f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1f600 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1f610 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
1f620 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
1f630 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1f640 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
1f650 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1f660 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1f670 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1f680 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1f690 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1f6a0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1f6b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1f6c0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1f6d0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1f6e0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1f6f0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1f700 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
1f710 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1f720 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1f730 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1f740 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1f750 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1f760 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1f770 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1f780 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1f790 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1f7a0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1f7b0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1f7c0 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1f7d0 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1f7e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1f7f0 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1f800 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1f810 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1f820 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1f830 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1f840 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1f850 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1f860 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1f870 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1f880 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1f890 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1f8a0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
1f8b0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1f8c0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1f8d0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1f8e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1f8f0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1f900 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1f910 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1f920 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
1f930 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
1f940 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1f950 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
1f960 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
1f970 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
1f980 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
1f990 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
1f9a0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
1f9b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1f9c0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
1f9d0 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
1f9e0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
1f9f0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
1fa00 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
1fa10 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
1fa20 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
1fa30 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
1fa40 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
1fa50 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1fa60 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1fa70 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
1fa80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1fa90 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {H13011} The [sq
1faa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1fab0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1fac0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1fad0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fae0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1faf0 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1fb00 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1fb10 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1fb20 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1fb30 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
1fb40 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {H13012} The [sq
1fb50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1fb60 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1fb70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1fb80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fb90 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
1fba0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
1fbb0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
1fbc0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
1fbd0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
1fbe0 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
1fbf0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1fc00 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48   order..**.** {H
1fc10 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
1fc20 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
1fc30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fc40 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
1fc50 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
1fc60 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
1fc70 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
1fc80 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20  n zero, the SQL 
1fc90 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  text is.**      
1fca0 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53      read from zS
1fcb0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1fcc0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1fcd0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1fce0 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68  * {H13014} If th
1fcf0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1fd00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1fd10 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1fd20 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
1fd30 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
1fd40 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d  variants is non-
1fd50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
1fd60 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79  t most nBytes by
1fd70 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
1fd80 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72     SQL text is r
1fd90 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a  ead from zSql..*
1fda0 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e  *.** {H13015} In
1fdb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fdc0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50  e_v2(db,zSql,N,P
1fdd0 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74  ,pzTail)] and it
1fde0 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20  s variants.**   
1fdf0 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53         if the zS
1fe00 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  ql input text co
1fe10 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e  ntains more than
1fe20 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65   one SQL stateme
1fe30 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  nt.**          a
1fe40 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  nd pzTail is not
1fe50 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54   NULL, then *pzT
1fe60 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1fe70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20  oint to the.**  
1fe80 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79          first by
1fe90 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1fea0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1feb0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1fec0 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ql..**          
1fed0 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20  <todo>What does 
1fee0 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f  *pzTail point to
1fef0 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65   if there is one
1ff00 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64   statement?</tod
1ff10 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36  o>.**.** {H13016
1ff20 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1ff30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1ff40 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1ff50 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29  ql,N,ppStmt,...)
1ff60 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
1ff70 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
1ff80 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f  ants writes into
1ff90 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74   *ppStmt a point
1ffa0 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
1ffb0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1ffc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
1ffd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  a pointer to NUL
1ffe0 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69  L if zSql contai
1fff0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ns.**          n
20000 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  othing other tha
20010 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20  n whitespace or 
20020 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  comments..**.** 
20030 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {H13019} The [sq
20040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20050 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
20060 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
20070 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
20080 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
20090 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
200a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
200b0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
200c0 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {H13021} Before
200d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
200e0 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
200f0 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
20100 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
20110 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
20120 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
20130 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20140 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c  an [SQLITE_OK]),
20150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
20160 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53  y first set *ppS
20170 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  tmt to NULL..*/.
20180 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
20190 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
201a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
201b0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
201c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
201d0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
201e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
201f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
20200 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
20210 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
20220 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
20230 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
20240 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
20250 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
20260 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
20270 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
20280 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
20290 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
202a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
202b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
202c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
202d0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
202e0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
202f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
20300 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
20310 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
20320 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
20330 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
20340 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
20350 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
20360 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
20370 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
20380 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
20390 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
203a0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
203b0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
203c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
203d0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
203e0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
203f0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
20400 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
20410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
20420 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20430 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
20440 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
20450 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
20460 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
20470 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
20480 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
20490 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
204a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
204b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
204c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
204d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
204e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
204f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
20500 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
20510 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
20520 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
20530 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
20540 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
20550 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
20560 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
20570 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
20580 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
20590 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
205a0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
205b0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
205c0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
205d0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
205e0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
205f0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
20600 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
20610 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
20620 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
20630 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
20640 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
20650 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
20660 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
20670 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
20680 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
20690 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
206a0 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76 69  APIREF: Retrievi
206b0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
206c0 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30   {H13100} <H1300
206d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
206e0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
206f0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
20700 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
20710 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
20720 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
20730 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
20740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
20750 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
20760 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
20770 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
20780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20790 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
207a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
207b0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
207c0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  TS:.**.** {H1310
207d0 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
207e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
207f0 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
20800 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
20810 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
20820 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
20830 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
20840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20850 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
20860 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
20870 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74  epare16_v2()], t
20880 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
20890 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ()] returns.**  
208a0 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
208b0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
208c0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f  inated string co
208d0 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38  ntaining a UTF-8
208e0 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20   rendering.**   
208f0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72         of the or
20900 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65  iginal SQL state
20910 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ment..**.** {H13
20920 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65  102} If the [pre
20930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20940 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
20950 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
20960 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20970 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
20980 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
20990 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
209a0 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
209b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
209c0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
209d0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
209e0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
209f0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
20a00 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
20a10 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
20a20 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69  qlite3_sql(S)] i
20a30 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
20a40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
20a50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20a60 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20  t] S is deleted 
20a70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
20a80 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a  inalize(S)]..*/.
20a90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20aa0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
20ab0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
20ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
20ad0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
20ae0 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48   Value Object {H
20af0 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15000} <S20200>.
20b00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
20b10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20b20 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
20b30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20b40 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
20b50 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
20b60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
20b70 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
20b80 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
20b90 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
20ba0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
20bb0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
20bc0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
20bd0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
20be0 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20   stores. Values 
20bf0 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
20c00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
20c10 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
20c20 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
20c30 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
20c40 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
20c50 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
20c60 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20c70 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
20c80 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
20c90 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
20ca0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
20cb0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
20cc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20cd0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
20ce0 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
20cf0 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
20d00 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
20d10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20d20 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
20d30 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
20d40 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
20d50 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
20d60 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
20d70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
20d80 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
20d90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20da0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
20db0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
20dc0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
20dd0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
20de0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
20df0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
20e00 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
20e10 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
20e20 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20e30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20e40 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
20e50 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
20e60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20e70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
20e80 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
20e90 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
20ea0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
20eb0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
20ec0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
20ed0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
20ee0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
20ef0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
20f00 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
20f10 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
20f20 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
20f30 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
20f40 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
20f50 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
20f60 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
20f70 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
20f80 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
20f90 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20fa0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
20fb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
20fc0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
20fd0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
20fe0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
20ff0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
21000 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
21010 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
21020 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
21030 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
21040 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
21050 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
21060 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  een between prot
21070 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
21080 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
21090 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
210a0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
210b0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
210c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
210d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
210e0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
210f0 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
21100 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
21110 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [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 73 5d 20   SQL functions] 
21140 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
21150 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
21160 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
21170 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
21180 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
21190 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
211a0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
211b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
211c0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
211d0 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
211e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
211f0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
21200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
21210 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
21220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
21230 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
21240 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
21250 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
21260 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
21270 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
21280 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
21290 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
212a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
212b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
212c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
212d0 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36  text Object {H16
212e0 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  001} <S20200>.**
212f0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
21300 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
21310 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
21320 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
21330 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
21340 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
21350 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
21360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
21370 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
21380 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
21390 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
213a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
213b0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
213c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
213d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
213e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
213f0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
21400 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
21410 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
21420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
21430 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
21440 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
21450 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
21460 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
21470 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
21480 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
21490 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
214a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
214b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
214c0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
214d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
214e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
214f0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
21500 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
21510 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
21520 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
21530 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
21540 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35  Statements {H135
21550 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20  00} <S70300>.** 
21560 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
21570 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
21580 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
21590 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
215a0 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
215b0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
215c0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
215d0 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
215e0 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ing}.**.** In th
215f0 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
21600 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
21610 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21620 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
21630 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
21640 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
21650 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e   parameter in on
21660 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  e of these forms
21670 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
21680 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
21690 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
216a0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
216b0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
216c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
216d0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
216e0 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
216f0 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
21700 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
21710 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c  and VVV is an al
21720 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
21730 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20  meter name. The 
21740 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
21750 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
21760 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
21770 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
21780 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
21790 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
217a0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
217b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
217c0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
217d0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
217e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
217f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
21800 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
21810 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
21820 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
21830 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
21840 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
21850 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
21860 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21870 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
21880 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
21890 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
218a0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
218b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
218c0 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74  set..** The left
218d0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
218e0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
218f0 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
21900 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
21910 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
21920 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
21930 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
21940 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
21950 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
21960 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
21970 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
21980 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64  ence..** The ind
21990 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
219a0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
219b0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
219c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
219d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
219e0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
219f0 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65  sired.  The inde
21a00 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
21a10 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
21a20 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
21a30 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
21a40 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
21a50 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
21a60 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
21a70 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
21a80 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
21a90 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
21aa0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
21ab0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
21ac0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
21ad0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
21ae0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
21af0 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f  *.** In those ro
21b00 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
21b10 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
21b20 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
21b30 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
21b40 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
21b50 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
21b60 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
21b70 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
21b80 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
21b90 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
21ba0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
21bb0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
21bc0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
21bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
21be0 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
21bf0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
21c00 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
21c10 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
21c20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
21c30 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
21c40 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   The fifth argum
21c50 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
21c60 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
21c70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
21c80 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
21c90 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
21ca0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
21cb0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
21cc0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
21cd0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
21ce0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
21cf0 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65   with it. If the
21d00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
21d10 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
21d20 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
21d30 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
21d40 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
21d50 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
21d60 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
21d70 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
21d80 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
21d90 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
21da0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74  ..** If the fift
21db0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
21dc0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
21dd0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
21de0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
21df0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
21e00 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
21e10 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
21e20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
21e30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21e40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
21e50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21e60 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
21e70 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
21e80 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
21e90 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
21ea0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
21eb0 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73  .  A zeroblob us
21ec0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
21ed0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
21ee0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
21ef0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
21f00 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
21f10 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
21f20 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
21f30 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
21f40 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
21f50 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
21f60 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
21f70 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
21f80 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21f90 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
21fa0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
21fb0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41  ] routines..** A
21fc0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
21fd0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
21fe0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
21ff0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
22000 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22010 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
22020 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
22030 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
22040 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22050 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
22060 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
22070 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
22080 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
22090 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
220a0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
220b0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
220c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
220d0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
220e0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
220f0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
22100 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
22110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
22120 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
22130 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
22140 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
22150 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
22160 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
22170 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
22180 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
22190 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
221a0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
221b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
221c0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
221d0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  loc() fails..** 
221e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
221f0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
22200 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
22210 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
22220 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
22230 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
22240 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
22250 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
22260 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
22270 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
22280 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
22290 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
222a0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
222b0 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
222c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
222d0 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
222e0 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
222f0 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
22300 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
22310 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
22320 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
22330 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
22340 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
22350 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
22360 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
22370 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
22380 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
22390 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
223a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
223b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
223c0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
223d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
223e0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
223f0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
22400 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68  *.** {H13506} Th
22410 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  e [SQL statement
22420 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67   compiler] recog
22430 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20  nizes tokens of 
22440 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20  the forms.**    
22450 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e        "?", "?NNN
22460 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56  ", "$VVV", ":VVV
22470 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73  ", and "@VVV" as
22480 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c   SQL parameters,
22490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
224a0 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65  re NNN is any se
224b0 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
224c0 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20   more digits.** 
224d0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
224e0 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65  re VVV is any se
224f0 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
22500 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72   more alphanumer
22510 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ic.**          c
22520 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a  haracters or "::
22530 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  " optionally fol
22540 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e  lowed by a strin
22550 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  g containing.** 
22560 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63           no spac
22570 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64  es and contained
22580 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65   within parenthe
22590 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ses..**.** {H135
225a0 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20  09} The initial 
225b0 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20  value of an SQL 
225c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
225d0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32  L..**.** {H13512
225e0 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
225f0 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65  n "?" SQL parame
22600 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65  ter is one large
22610 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20  r than the.**   
22620 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69         largest i
22630 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
22640 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66  meter to the lef
22650 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20  t, or 1 if.**   
22660 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69         the "?" i
22670 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53  s the leftmost S
22680 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  QL parameter..**
22690 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65  .** {H13515} The
226a0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e   index of an "?N
226b0 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  NN" SQL paramete
226c0 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72  r is the integer
226d0 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33   NNN..**.** {H13
226e0 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  518} The index o
226f0 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56  f an ":VVV", "$V
22700 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53  VV", or "@VVV" S
22710 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  QL parameter is.
22720 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22730 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65  same as the inde
22740 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63  x of leftmost oc
22750 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65  currences of the
22760 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
22770 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20    parameter, or 
22780 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  one more than th
22790 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
227a0 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  over all.**     
227b0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20       parameters 
227c0 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74  to the left if t
227d0 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74  his is the first
227e0 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20   occurrence.**  
227f0 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20          of this 
22800 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20  parameter, or 1 
22810 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c  if this is the l
22820 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65  eftmost paramete
22830 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31  r..**.** {H13521
22840 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
22850 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
22860 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51  ails with an [SQ
22870 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20  LITE_RANGE].**  
22880 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66          error if
22890 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
228a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
228b0 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a  s less than 1.**
228c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65            or gre
228d0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f  ater than the co
228e0 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54  mpile-time SQLIT
228f0 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
22900 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  UMBER.**        
22910 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
22920 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c  ** {H13524} Call
22930 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22940 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22950 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
22960 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
22970 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
22980 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
22990 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
229a0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
229b0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
229c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
229d0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
229e0 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c  ** {H13527} Call
229f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22a00 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22a10 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
22a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
22a30 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
22a40 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
22a50 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
22a60 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30  N..**.** {H13530
22a70 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
22a80 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
22a90 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
22aa0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
22ab0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
22ac0 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
22ad0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22ae0 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
22af0 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61  * {H13533} In ca
22b00 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
22b10 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
22b20 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
22b30 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
22b40 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
22b50 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
22b60 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22b70 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
22b80 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
22b90 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
22ba0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
22bb0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
22bc0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
22bd0 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
22be0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
22bf0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
22c00 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  H13536} In calls
22c10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22c20 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
22c30 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
22c40 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22c50 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
22c60 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
22c70 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
22c80 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
22c90 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
22ca0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
22cb0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
22cc0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39  e..**.** {H13539
22cd0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22ce0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22cf0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
22d00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22d10 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
22d20 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
22d30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22d40 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
22d50 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
22d60 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
22d70 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
22d80 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
22d90 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
22da0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
22db0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
22dc0 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
22dd0 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
22de0 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
22df0 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
22e00 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
22e10 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
22e20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
22e30 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  H13542} In calls
22e40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22e50 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
22e60 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
22e70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22e80 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
22e90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22ea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22eb0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
22ec0 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
22ed0 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
22ee0 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
22ef0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
22f00 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
22f10 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
22f20 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
22f30 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72  he value V befor
22f40 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
22f50 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20  .** {H13545} In 
22f60 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22f70 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
22f80 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
22f90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22fa0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22fb0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
22fc0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22fd0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22fe0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
22ff0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
23000 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
23010 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
23020 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
23030 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
23040 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
23050 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73  e V after it has
23060 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
23070 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  the value V..**.
23080 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63  ** {H13548} In c
23090 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
230a0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
230b0 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
230c0 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
230d0 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f       is a BLOB o
230e0 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
230f0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
23100 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
23110 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31  e..**.** {H13551
23120 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
23130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
23140 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
23150 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
23160 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
23170 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
23180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
23190 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
231a0 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
231b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
231c0 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
231d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
231e0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
231f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
23200 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
23210 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
23220 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
23230 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
23240 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
23250 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
23260 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
23270 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
23280 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
23290 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
232a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
232b0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
232c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
232d0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
232e0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
232f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
23300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23310 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
23320 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
23330 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
23340 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
23350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23360 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
23370 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
23380 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
23390 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
233a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
233b0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
233c0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
233d0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
233e0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
233f0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
23400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
23410 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
23420 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d  ameters {H13600}
23430 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
23440 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
23450 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
23460 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
23470 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
23480 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
23490 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
234a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
234b0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
234c0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
234d0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
234e0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
234f0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
23500 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
23510 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
23520 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
23530 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
23540 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
23550 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
23560 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
23570 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
23580 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
23590 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
235a0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
235b0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
235c0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
235d0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
235e0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
235f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
23600 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
23610 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
23620 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
23630 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
23640 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
23650 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
23660 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
23670 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
23680 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
23690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
236a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
236b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
236c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
236d0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
236e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
236f0 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73   {H13601} The [s
23700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23710 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20  meter_count(S)] 
23720 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23730 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
23740 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
23750 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  of all SQL param
23760 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  eters in the.** 
23770 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
23780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
23790 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61   or 0 if S conta
237a0 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
237b0 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
237c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
237d0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
237e0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
237f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
23800 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
23810 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53  eter {H13620} <S
23820 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70300>.**.** Thi
23830 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
23840 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23850 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
23860 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61  -th.** [SQL para
23870 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65  meter] in a [pre
23880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23890 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
238a0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
238b0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
238c0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
238d0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
238e0 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
238f0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
23900 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
23910 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
23920 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
23930 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
23940 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
23950 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
23960 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
23970 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
23980 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
23990 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
239a0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
239b0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
239c0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
239d0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f  .** and are also
239e0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
239f0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
23a00 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  eters"..**.** Th
23a10 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
23a20 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
23a30 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
23a40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
23a50 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
23a60 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
23a70 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
23a80 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
23a90 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
23aa0 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
23ab0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
23ac0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
23ad0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
23ae0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
23af0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
23b00 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
23b10 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
23b20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23b30 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
23b40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23b50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
23b60 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
23b70 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
23b80 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
23b90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23ba0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
23bb0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
23bc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23bd0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
23be0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
23bf0 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13621} The [sql
23c00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23c10 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ter_name(S,N)] i
23c20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55  .**          a U
23c40 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
23c50 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  f the name of th
23c60 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
23c70 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  in.**          t
23c80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23c90 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67  tement] S having
23ca0 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20   index N, or.** 
23cb0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66           NULL if
23cc0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c   there is no SQL
23cd0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
23ce0 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68  index N or if th
23cf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
23d00 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
23d10 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79  ex N is an anony
23d20 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22  mous parameter "
23d30 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ?"..*/.const cha
23d40 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
23d50 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
23d60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23d70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23d80 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
23d90 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
23da0 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
23db0 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
23dc0 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
23dd0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
23de0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
23df0 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
23e00 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
23e10 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
23e20 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
23e30 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
23e40 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
23e50 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
23e60 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
23e70 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
23e80 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
23e90 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
23ea0 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
23eb0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
23ec0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
23ed0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
23ee0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23ef0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
23f00 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
23f10 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
23f20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23f30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
23f40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
23f50 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
23f60 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
23f70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23f80 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
23f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
23fa0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
23fb0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
23fc0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23fd0 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  13641} The [sqli
23fe0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23ff0 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69  er_index(S,N)] i
24000 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
24020 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
24030 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b  rameter in the [
24040 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24050 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
24060 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74  S whose name mat
24070 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73  ches the UTF-8 s
24080 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66  tring N, or 0 if
24090 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20   there is.**    
240a0 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a        no match..
240b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
240c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
240d0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
240e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
240f0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
24100 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
24110 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
24120 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
24130 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30  nt {H13660} <S70
24140 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  300>.**.** Contr
24150 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
24160 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
24170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
24180 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
24190 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
241a0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
241b0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
241c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
241d0 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
241e0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
241f0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
24200 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
24210 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
24220 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b  * {H13661} The [
24230 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
24240 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
24250 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20  face resets all 
24260 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
24270 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
24280 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  gs in the [prepa
24290 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
242a0 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a   back to NULL..*
242b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
242c0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
242d0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
242e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
242f0 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
24300 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
24310 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30  {H13710} <S10700
24320 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
24330 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
24340 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
24350 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
24360 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
24370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
24380 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
24390 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
243a0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
243b0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
243c0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
243d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
243e0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
243f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24400 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65  .** {H13711} The
24410 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24420 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
24430 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24440 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
24450 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
24460 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
24470 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
24480 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24490 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
244a0 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20        or 0 if S 
244b0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
244c0 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  e a result set..
244d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
244e0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
244f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24510 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
24520 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
24530 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30  {H13720} <S10700
24540 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
24550 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
24560 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
24570 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
24580 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
24590 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
245a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
245b0 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
245c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
245d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
245e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
245f0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
24600 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
24610 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
24620 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
24630 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
24640 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
24650 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
24660 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
24670 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
24680 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24690 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
246a0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
246b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
246c0 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ent. The second 
246d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
246e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
246f0 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  r.  The leftmost
24700 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
24710 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
24720 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
24730 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
24740 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
24750 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24760 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
24770 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
24780 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
24790 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
247a0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
247b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
247c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
247d0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
247e0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
247f0 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
24800 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
24810 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
24820 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
24830 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
24840 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
24850 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
24860 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
24870 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
24880 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
24890 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
248a0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
248b0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
248c0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
248d0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
248e0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
248f0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
24900 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
24910 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
24920 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
24930 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
24940 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
24950 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
24960 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
24970 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
24980 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  e next..**.** IN
24990 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
249a0 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65  {H13721} A succe
249b0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
249c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
249d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
249e0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
249f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24a00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24a10 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
24a20 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
24a30 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
24a40 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
24a50 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
24a60 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
24a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24a80 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
24a90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
24aa0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
24ab0 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73  H13723} A succes
24ac0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
24ad0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
24ae0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
24af0 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
24b00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24b10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24b20 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
24b30 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
24b40 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
24b50 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
24b60 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
24b70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24b80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24b90 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
24ba0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
24bb0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  16 string.**    
24bc0 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
24bd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24be0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54  **.** {H13724} T
24bf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24c00 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b  mn_name()] and [
24c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24c20 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ame16()].**     
24c30 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
24c40 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
24c50 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72  inter if they ar
24c60 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20  e unable to.**  
24c70 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
24c80 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
24c90 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
24ca0 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
24cb0 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74  ** {H13725} If t
24cc0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
24cd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
24ce0 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
24cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24d00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24d10 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
24d20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
24d30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
24d40 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
24d50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
24d60 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20  .**.** {H13726} 
24d70 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
24d80 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
24d90 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
24da0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
24db0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24dc0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
24dd0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
24de0 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20  the next.**     
24df0 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74       call to eit
24e00 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68  her routine with
24e10 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20   the same S and 
24e20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
24e30 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
24e40 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  l [sqlite3_final
24e50 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
24e60 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37  d..**.** {H13727
24e70 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  } When a result 
24e80 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
24e90 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
24ea0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
24eb0 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65      an AS clause
24ec0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
24ed0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  at column is the
24ee0 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20   identifier.**  
24ef0 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
24f00 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
24f10 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
24f20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
24f30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
24f40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
24f50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24f70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
24f80 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
24f90 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
24fa0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
24fb0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
24fc0 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3740} <S10700>.*
24fd0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24fe0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
24ff0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
25000 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
25010 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
25020 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
25030 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53  a result of a [S
25040 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25050 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
25060 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
25070 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
25080 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
25090 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
250a0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
250b0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
250c0 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
250d0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
250e0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
250f0 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
25100 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
25110 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
25120 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
25130 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
25140 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
25150 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
25160 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
25170 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
25180 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25190 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
251a0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
251b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
251c0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
251d0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
251e0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
251f0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
25200 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
25210 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
25220 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
25230 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
25240 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
25250 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
25260 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
25270 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
25280 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
25290 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
252a0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
252b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
252c0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
252d0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
252e0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
252f0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
25300 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
25310 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
25320 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
25330 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
25340 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
25350 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
25360 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
25370 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
25380 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
25390 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
253a0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
253b0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
253c0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
253d0 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  * NULL.  These r
253e0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
253f0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
25400 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
25410 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
25420 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
25430 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
25440 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
25450 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
25460 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f   table.** and co
25470 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
25480 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
25490 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
254a0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
254b0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
254c0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
254d0 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
254e0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
254f0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
25500 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
25510 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
25520 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
25530 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
25540 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
25550 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
25560 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
25570 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
25580 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
25590 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
255a0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
255b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  ined..**.** {A13
255c0 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
255d0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
255e0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
255f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
25600 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
25610 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
25620 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
25630 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
25640 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
25650 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
25660 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
25670 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25680 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {H13741} The [sq
25690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
256a0 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
256b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
256c0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
256d0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
256e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
256f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
25700 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
25710 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
25720 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
25730 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
25740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25750 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
25760 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
25770 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
25780 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
25790 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
257a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
257b0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
257c0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
257d0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
257e0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54  **.** {H13742} T
257f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25800 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25810 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
25820 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
25830 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
25840 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
25850 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
25860 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
25870 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
25880 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
25890 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
258a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
258b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
258c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
258d0 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
258e0 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
258f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25900 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
25910 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
25920 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
25930 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25940 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
25950 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
25960 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {H13743} The [s
25970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
25980 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
25990 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
259a0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
259b0 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
259c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
259d0 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
259e0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
259f0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
25a00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
25a10 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25a20 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
25a30 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
25a40 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
25a50 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25a60 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
25a70 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
25a80 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
25a90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25aa0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
25ab0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
25ac0 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {H13744} The [s
25ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
25ae0 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
25af0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25b00 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
25b10 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
25b20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
25b30 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
25b40 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
25b50 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
25b60 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
25b70 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
25b80 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
25b90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25ba0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
25bb0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
25bc0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
25bd0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
25be0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
25bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25c00 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25c10 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25c20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25c30 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54  **.** {H13745} T
25c40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25c50 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
25c60 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25c70 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
25c80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
25c90 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
25ca0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
25cb0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
25cc0 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
25cd0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
25ce0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
25cf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25d00 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
25d10 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
25d20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
25d30 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
25d40 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
25d50 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
25d60 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
25d70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
25d80 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
25d90 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
25da0 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
25db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25dc0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
25dd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25de0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
25df0 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
25e00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
25e10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
25e20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
25e30 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  le.**          c
25e40 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
25e50 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
25e60 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
25e70 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
25e80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25e90 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
25ea0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
25eb0 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  h column.**     
25ec0 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67       of S is a g
25ed0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
25ee0 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
25ef0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
25f00 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
25f10 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
25f20 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20  .**.** {H13748} 
25f30 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
25f40 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
25f50 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
25f60 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25f70 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
25f80 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
25f90 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
25fa0 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66  alid for the lif
25fb0 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72  etime of the [pr
25fc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25fd0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
25fe0 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64   until the encod
25ff0 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62  ing is changed b
26000 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61  y another metada
26010 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ta.**          i
26020 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f  nterface call fo
26030 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61  r the same prepa
26040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
26050 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
26060 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
26070 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74  ** {A13751} If t
26080 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
26090 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
260a0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
260b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
260c0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
260d0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
260e0 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
260f0 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
26100 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
26110 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
26120 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
26130 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
26140 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
26150 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
26160 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
26170 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
26180 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
26190 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
261a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
261b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
261c0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
261d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
261e0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
261f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
26200 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
26210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26220 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
26240 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
26250 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26260 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26270 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
26280 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
26290 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
262a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
262b0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
262c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
262d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
262e0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
262f0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
26300 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
26310 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
26320 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
26330 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
26340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26350 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
26360 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
26370 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
26380 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
26390 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
263a0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
263b0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
263c0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
263d0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
263e0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
263f0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
26400 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
26410 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
26420 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
26430 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
26440 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
26450 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
26460 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
26470 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
26480 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
26490 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
264a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
264b0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
264c0 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
264d0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
264e0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
264f0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
26500 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
26510 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
26520 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
26530 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
26540 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
26550 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
26560 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
26570 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
26580 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
26590 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
265a0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
265b0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
265c0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
265d0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
265e0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
265f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
26600 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
26610 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
26620 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
26630 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
26640 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
26650 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
26660 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
26670 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
26680 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
26690 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
266a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
266b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
266c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
266d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
266e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
266f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
26700 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
26710 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
26720 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
26730 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
26740 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
26750 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
26760 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
26770 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
26780 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20  **.** {H13761}  
26790 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
267a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
267b0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
267c0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  N)] returns a.**
267d0 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d             zero-
267e0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
267f0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
26800 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
26810 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20  datatype.**     
26820 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62        of the tab
26830 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
26840 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74  ppears as the Nt
26850 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
26860 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
26870 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
26880 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
26890 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
268a0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
268b0 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  H13762}  A succe
268c0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
268d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
268e0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
268f0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
26900 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
26910 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
26920 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
26930 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
26940 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
26950 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
26960 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
26970 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
26980 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
26990 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
269a0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
269b0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
269c0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
269d0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
269e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
269f0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
26a00 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
26a10 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
26a20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
26a30 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
26a40 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
26a50 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
26a60 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26a70 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
26a80 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68          or if th
26a90 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
26aa0 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  S is an expressi
26ab0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72  on or subquery r
26ac0 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ather.**        
26ad0 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20     than a table 
26ae0 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20  column, or if a 
26af0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
26b00 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20  n failure.**    
26b10 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
26b20 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f  ring encoding co
26b30 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a  nversions, then.
26b40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c  **           cal
26b50 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
26b60 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
26b70 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
26b80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
26b90 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
26ba0 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c  S,N)] return NUL
26bb0 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  L..*/.const char
26bc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26bd0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
26be0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26bf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
26c00 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
26c10 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
26c20 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
26c30 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
26c40 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
26c50 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30  nt {H13200} <S10
26c60 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  000>.**.** After
26c70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26c80 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
26c90 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
26ca0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
26cb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26cc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26cd0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
26ce0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
26cf0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
26d00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26d10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
26d20 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
26d30 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
26d40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
26d50 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
26d60 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
26d70 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
26d80 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
26d90 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
26da0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
26db0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
26dc0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
26dd0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
26de0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
26df0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
26e00 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
26e10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26e20 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
26e30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26e40 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
26e50 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26e60 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
26e70 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
26e80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26e90 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
26ea0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
26eb0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
26ec0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
26ed0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
26ee0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
26ef0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
26f00 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
26f10 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
26f20 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
26f30 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
26f40 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
26f50 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
26f60 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
26f70 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
26f80 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
26f90 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
26fa0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
26fb0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
26fc0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
26fd0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
26fe0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
26ff0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
27000 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
27010 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
27020 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
27030 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
27040 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
27050 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
27060 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
27070 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
27080 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
27090 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
270a0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
270b0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
270c0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
270d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
270e0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
270f0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
27100 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
27110 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
27120 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
27130 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
27140 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
27150 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
27160 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
27170 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
27180 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
27190 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
271a0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
271b0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
271c0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
271d0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
271e0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
271f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
27200 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
27210 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
27220 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
27230 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
27240 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
27250 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
27260 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
27270 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
27280 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
27290 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
272a0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
272b0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
272c0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
272d0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
272e0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
272f0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
27300 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
27310 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
27320 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
27330 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
27340 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
27350 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
27360 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
27370 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
27380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
27390 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
273a0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
273b0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
273c0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  **.** [SQLITE_ER
273d0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
273e0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
273f0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
27400 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
27410 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
27420 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
27430 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
27440 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
27450 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
27460 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
27470 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
27480 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
27490 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68  rmsg()]..** With
274a0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
274b0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
274c0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
274d0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
274e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
274f0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
27500 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
27510 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
27520 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
27530 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
27540 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
27550 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
27560 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27570 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
27580 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
27590 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
275a0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
275b0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
275c0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
275d0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
275e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
275f0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
27600 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
27610 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
27620 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
27630 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
27640 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
27650 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
27660 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
27670 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
27680 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
27690 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
276a0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
276b0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
276c0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
276d0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
276e0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
276f0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
27700 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
27710 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
27720 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
27730 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
27740 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
27750 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
27760 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
27770 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
27780 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
27790 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
277a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
277b0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
277c0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
277d0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
277e0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
277f0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
27800 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
27810 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
27820 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
27830 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
27840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
27860 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
27870 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
27880 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
27890 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
278a0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
278b0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
278c0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
278d0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
278e0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
278f0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
27900 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
27910 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27920 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
27930 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
27940 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
27950 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
27960 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27970 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
27980 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
27990 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
279a0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
279b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
279c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
279d0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
279e0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
279f0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
27a00 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
27a10 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
27a20 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
27a30 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
27a40 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
27a50 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
27a60 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
27a70 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
27a80 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20  H13202}  If the 
27a90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27aa0 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
27ab0 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a  to be run, then.
27ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
27ad0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
27ae0 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
27af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27b00 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
27b10 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72     completion or
27b20 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61   until it is rea
27b30 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f  dy to return ano
27b40 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a  ther row of the.
27b50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73  **           res
27b60 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69  ult set, or unti
27b70 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l an [sqlite3_in
27b80 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
27b90 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  upt].**         
27ba0 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20    or a run-time 
27bb0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
27bc0 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68  .** {H15304}  Wh
27bd0 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
27be0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
27bf0 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61  auses the [prepa
27c00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27c10 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f  *           S to
27c20 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
27c30 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  on, the function
27c40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
27c50 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DONE]..**.** {H
27c60 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
27c70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27c80 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
27c90 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
27ca0 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  dy to.**        
27cb0 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65     return anothe
27cc0 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
27cd0 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
27ce0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
27cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d  ..**.** {H15308}
27d00 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b    If a call to [
27d10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27d20 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a   encounters an.*
27d30 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27d40 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
27d50 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
27d60 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
27d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
27d80 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
27d90 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
27da0 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
27db0 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
27dc0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
27dd0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
27de0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
27df0 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20  **.** {H15310}  
27e00 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
27e10 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
27e20 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74  rupt] or a run-t
27e30 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
27e40 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
27e50 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
27e60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
27e80 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
27e90 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
27ea0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
27eb0 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
27ec0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
27ed0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
27ee0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27ef0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27f00 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  ], then the func
27f10 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
27f20 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
27f30 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
27f40 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
27f50 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
27f60 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
27f70 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
27f80 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
27f90 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27fa0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
27fb0 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37  result set {H137
27fc0 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  70} <S10700>.**.
27fd0 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e  ** Returns the n
27fe0 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
27ff0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28000 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28010 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   set..**.** INVA
28020 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
28030 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20  13771}  After a 
28040 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28050 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72  _step(S)] that r
28060 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
28070 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  OW],.**         
28080 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    the [sqlite3_d
28090 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f  ata_count(S)] ro
280a0 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
280b0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
280c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
280d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
280e0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
280f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
28100 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  H13772}  After [
28110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
28120 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
28130 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
28140 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
28150 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
28160 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
28170 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
28180 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a  n called on the.
28190 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
281a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281b0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
281c0 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
281d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
281e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
281f0 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b  | prepared] or [
28200 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20  sqlite3_reset | 
28210 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20  reset],.**      
28220 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
28230 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
28240 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
28250 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
28260 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
28270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28280 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28290 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
282a0 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48  tal Datatypes {H
282b0 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c  10265} <S10110><
282c0 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10120>.** KEYWO
282d0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
282e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20  .**.** {H10266} 
282f0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
28300 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
28310 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
28320 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
28330 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
28340 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
28350 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
28360 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
28370 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
28380 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
28390 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
283a0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
283b0 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
283c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
283d0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
283e0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
283f0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
28400 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
28410 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
28420 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
28430 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
28440 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
28450 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
28460 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
28470 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
28480 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
28490 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
284a0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
284b0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
284c0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
284d0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
284e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
284f0 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
28500 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
28510 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
28520 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
28530 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
28540 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
28550 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
28560 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
28570 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
28580 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
28590 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
285a0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
285b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
285c0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
285d0 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33  rom A Query {H13
285e0 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  800} <S10700>.**
285f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
28600 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
28610 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
28620 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
28630 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71  he "result set q
28640 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e  uery" interface.
28650 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28660 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
28670 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
28680 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
28690 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
286a0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
286b0 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72   query.  In ever
286c0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
286d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
286e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
286f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28700 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
28710 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
28720 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
28730 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
28740 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
28750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28760 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
28770 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
28780 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
28790 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
287a0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
287b0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
287c0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
287d0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
287e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
287f0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
28800 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
28810 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  dex 0..**.** If 
28820 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
28830 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
28840 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
28850 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
28860 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
28870 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
28880 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
28890 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
288a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
288b0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
288c0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
288d0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
288e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
288f0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
28900 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
28910 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
28920 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28930 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
28940 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
28950 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
28960 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
28970 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
28980 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
28990 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
289a0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
289b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
289c0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
289d0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
289e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
289f0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
28a00 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
28a10 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
28a20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
28a30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28a40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
28a50 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
28a60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
28a70 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
28a80 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
28a90 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
28aa0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
28ab0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
28ac0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
28ad0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
28ae0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28af0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
28b00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28b10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
28b20 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
28b30 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
28b40 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
28b50 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
28b60 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
28b70 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
28b80 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
28b90 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
28ba0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
28bb0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
28bc0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
28bd0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
28be0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
28bf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
28c00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
28c10 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
28c20 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
28c30 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
28c40 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
28c50 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
28c60 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
28c70 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
28c80 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
28c90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28ca0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
28cb0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
28cc0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
28cd0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
28ce0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
28cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28d00 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
28d10 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
28d20 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
28d30 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
28d40 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
28d50 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
28d60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28d70 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
28d80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
28d90 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
28da0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
28db0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
28dc0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
28dd0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
28de0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28df0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
28e00 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
28e10 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
28e20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
28e30 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
28e40 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
28e50 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
28e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28e70 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
28e80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
28e90 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
28ea0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
28eb0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
28ec0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
28ed0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28ee0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
28ef0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
28f00 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
28f10 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
28f20 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
28f30 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
28f40 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
28f50 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
28f60 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
28f70 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
28f80 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
28f90 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28fa0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
28fb0 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
28fc0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28fd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
28fe0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28ff0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
29000 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
29010 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
29020 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
29030 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
29040 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
29050 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
29060 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
29070 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69   BLOB is an arbi
29080 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
29090 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
290a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
290b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
290c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
290d0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
290e0 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
290f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
29100 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
29110 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
29120 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
29130 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
29140 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65  of UTF-8..** The
29150 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29160 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
29170 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
29180 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74  **.** The object
29190 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
291a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
291b0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
291c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
291d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
291e0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
291f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29200 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
29210 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
29220 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
29230 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
29240 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
29250 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
29260 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
29270 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
29280 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
29290 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
292a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
292b0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
292c0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
292d0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
292e0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
292f0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
29300 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
29310 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
29320 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
29330 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
29340 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
29350 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
29360 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
29370 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
29380 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
29390 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
293a0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
293b0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
293c0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
293d0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
293e0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
293f0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
29400 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
29410 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
29420 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
29430 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
29440 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
29450 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
29460 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
29470 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
29480 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
29490 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
294a0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
294b0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
294c0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
294d0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
294e0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
294f0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
29500 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
29510 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
29520 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
29530 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
29540 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
29550 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
29560 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
29570 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
29580 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
29590 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
295a0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
295b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
295c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
295d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
295e0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
295f0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
29600 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
29610 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
29620 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
29630 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
29640 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
29650 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
29660 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
29670 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
29680 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
29690 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
296a0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
296b0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
296c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
296d0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
296e0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
296f0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
29700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
29710 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
29720 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
29730 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
29740 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
29750 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
29760 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29770 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
29780 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
29790 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
297a0 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
297b0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
297c0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
297d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
297e0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
297f0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
29800 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29810 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
29820 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
29830 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29840 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
29850 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
29860 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
29870 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
29880 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29890 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
298a0 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
298b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
298c0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
298d0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
298e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
298f0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
29900 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
29910 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
29920 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
29930 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
29940 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
29950 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
29960 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
29970 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
29980 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
29990 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
299a0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
299b0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
299c0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
299d0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
299e0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
299f0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
29a00 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
29a10 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
29a20 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
29a30 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
29a40 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
29a50 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
29a60 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
29a70 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
29a80 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
29a90 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
29aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29ab0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
29ac0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
29ad0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
29ae0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
29af0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
29b00 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
29b10 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
29b20 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
29b30 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
29b40 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
29b50 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
29b60 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29b70 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29b80 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
29b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
29ba0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
29bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29bc0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
29bd0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
29be0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
29bf0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
29c00 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
29c10 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
29c20 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
29c30 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
29c40 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29c50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
29c60 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
29c70 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29c80 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
29c90 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
29ca0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
29cb0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
29cc0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29cd0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29ce0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
29cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29d00 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
29d10 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
29d20 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
29d30 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
29d40 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29d50 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
29d60 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
29d70 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73  l>.**.** Convers
29d80 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
29d90 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
29da0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
29db0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
29dc0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
29dd0 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
29de0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
29df0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
29e00 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
29e10 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
29e20 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
29e30 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
29e40 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
29e50 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
29e60 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
29e70 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
29e80 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
29e90 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
29ea0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
29eb0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
29ec0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
29ed0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
29ee0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
29ef0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
29f00 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
29f10 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
29f20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
29f30 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
29f40 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
29f50 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
29f60 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
29f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29f80 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
29f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29fa0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
29fb0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
29fc0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
29fd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29fe0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
29ff0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2a000 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2a010 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2a020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a030 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2a040 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2a050 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2a060 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2a070 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2a080 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2a090 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2a0a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a0b0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2a0c0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2a0d0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2a0e0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2a0f0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2a100 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2a110 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2a120 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2a130 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2a140 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2a150 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2a160 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2a170 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2a180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2a190 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2a1a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2a1b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2a1c0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2a1d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2a1e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2a1f0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2a200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a210 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
2a220 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2a230 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
2a240 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
2a250 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
2a260 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
2a270 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
2a280 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2a290 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2a2a0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2a2b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2a2c0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
2a2d0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2a2e0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2a2f0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2a300 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2a310 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2a320 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2a330 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2a340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2a350 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2a360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a370 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2a380 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2a390 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
2a3a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2a3b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2a3c0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2a3d0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2a3e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2a3f0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2a400 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2a410 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2a420 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2a430 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2a440 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2a450 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2a460 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2a470 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2a480 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2a490 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2a4a0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2a4b0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
2a4c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2a4d0 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b  * {H13803} The [
2a4e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a4f0 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(S,N)] interf
2a500 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2a510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2a520 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2a530 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2a540 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2a550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2a560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a570 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42  ment] S into a B
2a580 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74  LOB and then ret
2a590 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
2a5a0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
2a5b0 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
2a5c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36  e..**.** {H13806
2a5d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a5e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
2a5f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a600 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
2a610 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
2a620 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20  tes in the BLOB 
2a630 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
2a640 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
2a650 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
2a660 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
2a670 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
2a680 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2a690 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
2a6a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2a6b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a6c0 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
2a6d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2a6e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
2a6f0 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
2a700 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
2a710 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a720 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2a730 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2a740 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
2a750 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2a760 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
2a770 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
2a780 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
2a790 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
2a7a0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
2a7b0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2a7c0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
2a7d0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a7e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a7f0 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
2a800 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {H13812} The [s
2a810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a820 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
2a830 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2a840 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2a850 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2a860 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2a870 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2a880 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2a890 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a8a0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2a8b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2a8c0 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
2a8d0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2a8e0 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
2a8f0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35  e..**.** {H13815
2a900 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a910 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
2a920 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a930 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a940 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a950 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a960 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a970 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
2a980 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a990 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2a9a0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2a9b0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2a9c0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2a9d0 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
2a9e0 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
2a9f0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eger..**.** {H13
2aa00 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  818} The [sqlite
2aa10 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53  3_column_int64(S
2aa20 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2aa30 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2aa40 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2aa50 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2aa60 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2aa70 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
2aa80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2aa90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2aaa0 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
2aab0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2aac0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2aad0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2aae0 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
2aaf0 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54  **.** {H13821} T
2ab00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2ab10 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e  mn_text(S,N)] in
2ab20 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2ab30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ab40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2ab50 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2ab60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2ab70 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2ab80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ab90 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2aba0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2abb0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
2abc0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2abd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2abe0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2abf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d  ..**.** {H13824}
2ac00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2ac10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29  lumn_text16(S,N)
2ac20 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2ac30 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2ac40 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2ac50 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2ac60 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2ac70 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2ac80 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2ac90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2aca0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2acb0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2acc0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2acd0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2ace0 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
2acf0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2ad00 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
2ad10 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2ad20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
2ad30 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2ad40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
2ad50 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2ad60 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2ad70 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2ad80 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2ad90 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2ada0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2adb0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2adc0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2add0 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2ade0 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2adf0 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
2ae00 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2ae10 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ae20 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2ae30 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2ae40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ae50 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30  S..**.** {H13830
2ae60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2ae70 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29  olumn_value(S,N)
2ae80 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2ae90 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2aea0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20    pointer to an 
2aeb0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2aec0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2aed0 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ct for the.**   
2aee0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2aef0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2af00 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2af10 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2af20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2af30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2af40 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  S..*/.const void
2af50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2af60 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2af70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2af80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2af90 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2afa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2afb0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2afc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2afd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2afe0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2aff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2b000 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2b010 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2b020 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2b030 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2b040 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b050 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2b060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2b070 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2b080 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2b090 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2b0a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b0b0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2b0c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b0d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b0f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b100 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2b110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b120 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2b130 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2b140 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2b150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2b160 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b170 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2b180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2b190 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2b1a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2b1b0 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30   {H13300} <S7030
2b1c0 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
2b1d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
2b1e0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2b1f0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2b200 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2b210 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2b220 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2b230 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
2b240 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
2b250 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
2b260 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
2b270 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
2b280 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  . If execution o
2b290 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2b2a0 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a  failed then an.*
2b2b0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
2b2c0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2b2d0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2b2e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
2b2f0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2b300 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2b310 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
2b320 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
2b330 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2b340 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20  ement].  If the 
2b350 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2b360 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
2b370 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
2b380 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
2b390 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
2b3a0 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
2b3b0 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
2b3c0 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
2b3d0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
2b3e0 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f  errupt]..** Inco
2b3f0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
2b400 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
2b410 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
2b420 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
2b430 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2b440 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
2b450 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
2b460 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
2b470 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
2b480 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
2b490 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2b4a0 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {H11302} The [s
2b4b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b4c0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
2b4d0 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
2b4e0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2b4f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
2b500 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
2b510 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
2b520 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
2b530 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
2b540 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
2b550 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {H11304} If the 
2b560 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2b570 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b580 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2b590 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2b5a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b5b0 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
2b5c0 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
2b5d0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
2b5e0 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
2b5f0 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
2b600 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
2b610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2b620 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b640 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2b650 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2b660 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53  ject {H13330} <S
2b670 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70300>.**.** The
2b680 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2b690 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2b6a0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2b6b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b6c0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2b6d0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2b6e0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2b6f0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2b700 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
2b710 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2b720 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2b730 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2b740 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2b750 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2b760 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2b770 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2b780 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2b790 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2b7a0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2b7b0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2b7c0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ngs..**.** {H113
2b7d0 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
2b7e0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2b7f0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2b800 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b810 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
2b820 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
2b830 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2b840 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
2b850 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  H11334} If the m
2b860 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b870 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b880 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b890 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2b8a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2b8b0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2b8c0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2b8d0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
2b8e0 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
2b8f0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2b900 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2b910 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2b920 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2b930 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b940 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2b950 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
2b960 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
2b970 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2b980 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2b990 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2b9a0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2b9b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2b9c0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2b9d0 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
2b9e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2b9f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2ba00 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2ba10 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2ba20 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b  * {H11338} The [
2ba30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2ba40 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2ba50 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2ba60 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
2ba70 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
2ba80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
2ba90 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
2baa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bab0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
2bac0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2bad0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2bae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2baf0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2bb00 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2bb10 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30  ns {H16100} <S20
2bb20 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
2bb30 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2bb40 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2bb50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2bb60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2bb70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2bb80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2bb90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2bba0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2bbb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
2bbc0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2bbd0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2bbe0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2bbf0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2bc00 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2bc10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2bc20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2bc30 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2bc40 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2bc50 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2bc60 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2bc70 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2bc80 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
2bc90 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
2bca0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
2bcb0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
2bcc0 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
2bcd0 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
2bce0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
2bcf0 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
2bd00 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
2bd10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2bd20 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
2bd30 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2bd40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
2bd50 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2bd60 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2bd70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bd80 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2bd90 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2bda0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2bdb0 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
2bdc0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
2bdd0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
2bde0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2bdf0 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74  on internally, t
2be00 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  hen SQL function
2be10 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
2be20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a  individually to.
2be30 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65  ** each database
2be40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
2be50 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
2be60 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2be70 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2be80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2be90 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2bea0 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67  fined.  The leng
2beb0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2bec0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2bed0 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
2bee0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
2bef0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
2bf00 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2bf10 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2bf20 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
2bf30 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41  * characters.  A
2bf40 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2bf50 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2bf60 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2bf70 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2bf80 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
2bf90 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
2bfa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  ed..**.** The th
2bfb0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
2bfc0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
2bfd0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2bfe0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
2bff0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2c000 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
2c010 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2c020 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
2c030 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2c040 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2c050 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2c060 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2c070 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
2c080 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c090 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
2c0a0 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
2c0b0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
2c0c0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
2c0d0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
2c0e0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
2c0f0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
2c100 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
2c110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
2c120 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
2c130 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
2c140 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2c150 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2c160 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2c170 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2c180 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2c190 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2c1a0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2c1b0 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77  er.  It is allow
2c1c0 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
2c1d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c1e0 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2c1f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c200 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2c210 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2c220 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2c230 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2c240 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2c250 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
2c260 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2c270 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2c280 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2c290 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2c2a0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2c2b0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2c2c0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2c2d0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2c2e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2c2f0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2c300 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2c310 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2c320 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2c330 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2c340 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2c350 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2c360 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2c370 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2c380 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
2c390 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
2c3a0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
2c3b0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2c3c0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
2c3d0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
2c3e0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
2c3f0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
2c400 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2c410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
2c420 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
2c430 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
2c440 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2c450 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2c460 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2c470 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2c480 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2c490 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2c4a0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2c4b0 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
2c4c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2c4d0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2c4e0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
2c4f0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
2c500 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
2c510 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
2c520 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
2c530 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
2c540 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
2c550 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2c560 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2c570 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2c580 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2c590 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2c5a0 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
2c5b0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
2c5c0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2c5d0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2c5e0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2c5f0 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
2c600 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2c610 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
2c620 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
2c630 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
2c640 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2c650 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2c660 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
2c670 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2c680 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
2c690 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
2c6a0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
2c6b0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
2c6c0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
2c6d0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
2c6e0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
2c6f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2c700 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
2c710 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2c720 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2c730 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2c740 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69   used.  A functi
2c750 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2c760 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
2c770 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
2c780 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
2c790 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
2c7a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2c7b0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
2c7c0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
2c7d0 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  .  A function wh
2c7e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
2c7f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
2c800 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
2c810 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2c820 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
2c830 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2c840 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2c850 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2c860 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75  erent.  .** A fu
2c870 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2c880 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2c890 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
2c8a0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
2c8b0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
2c8c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2c8d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2c8e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2c8f0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
2c900 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
2c910 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74  F16..**.** Built
2c920 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2c930 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2c940 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2c950 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c960 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ions..** The fir
2c970 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  st application-d
2c980 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c990 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d  with a given nam
2c9a0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a  e overrides all.
2c9b0 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63  ** built-in func
2c9c0 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d  tions in the sam
2c9d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2c9e0 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65  ection] with the
2c9f0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53   same name..** S
2ca00 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
2ca10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ca20 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
2ca30 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
2ca40 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
2ca50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ca60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
2ca70 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
2ca80 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
2ca90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
2caa0 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
2cab0 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
2cac0 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74  *.** An applicat
2cad0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2cae0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2caf0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2cb00 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2cb10 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2cb20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2cb30 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2cb40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2cb50 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2cb60 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2cb70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2cb80 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2cb90 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2cba0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2cbb0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2cbc0 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  H16103} The [sql
2cbd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cbe0 74 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d  tion16(D,X,...)]
2cbf0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2cc00 20 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 20   behave.**      
2cc10 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f      as [sqlite3_
2cc20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2cc30 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 65  D,X,...)] in eve
2cc40 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68  ry way except th
2cc50 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  at it.**        
2cc60 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65    interprets the
2cc70 20 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a   X argument as z
2cc80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2cc90 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
2cca0 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72    native byte or
2ccb0 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  der instead of a
2ccc0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2ccd0 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
2cce0 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  H16106} A succes
2ccf0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
2cd00 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2cd10 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2cd20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2cd30 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
2cd40 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74  ace shall regist
2cd50 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
2cd60 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62  r replaces callb
2cd70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e  ack functions in
2cd80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2cd90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2cda0 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f           used to
2cdb0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2cdc0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
2cdd0 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d  d X with N param
2cde0 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
2cdf0 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70    and having a p
2ce00 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2ce10 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a  coding of E..**.
2ce20 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75  ** {H16109} A su
2ce30 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call 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 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
2ce70 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65          shall re
2ce80 70 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c 20  place the P, F, 
2ce90 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20  S, and L values 
2cea0 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63  from any prior c
2ceb0 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20  alls with.**    
2cec0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44        the same D
2ced0 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61  , X, N, and E va
2cee0 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  lues..**.** {H16
2cef0 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  112} The [sqlite
2cf00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cf10 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65  n(D,X,...)] inte
2cf20 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c  rface shall fail
2cf30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
2cf40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2cf50 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20   name X is.**   
2cf60 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68         longer th
2cf70 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63  an 255 bytes exc
2cf80 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
2cf90 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
2cfa0 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 68  *.** {H16118} Th
2cfb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2cfc0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2cfd0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74  ,E,P,F,S,L)] int
2cfe0 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
2cff0 20 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 6e     shall fail un
2d000 6c 65 73 73 20 65 69 74 68 65 72 20 46 20 69 73  less either F is
2d010 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
2d020 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
2d030 72 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 20  r.***         F 
2d040 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20  is non-NULL and 
2d050 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c  S and L are NULL
2d060 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d  ..**.** {H16121}
2d070 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2d080 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2d090 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2d0a0 73 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 68  shall fails with
2d0b0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
2d0c0 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
2d0d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74  QLITE_BUSY] if t
2d0e0 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70  here exist [prep
2d0f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2d100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
2d110 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2d120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d130 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2d140 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71  {H16124} The [sq
2d150 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d160 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2d170 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2d180 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20  l fail with.**  
2d190 20 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f 72          an error
2d1a0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2d1b0 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d  _ERROR] if param
2d1c0 65 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a 2a  eter N is less.*
2d1d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
2d1e0 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2d1f0 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48  an 127..**.** {H
2d200 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73  16127} When N is
2d210 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2d220 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2d230 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2d240 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2d250 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 68      interface sh
2d260 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c  all register cal
2d270 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2d280 6f 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  oked for the.** 
2d290 20 20 20 20 20 20 20 20 20 53 51 4c 20 66 75 6e           SQL fun
2d2a0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2d2b0 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74    named X when t
2d2c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2d2d0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2d2e0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  L function is.**
2d2f0 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c            exactl
2d300 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  y N..**.** {H161
2d310 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31  30} When N is -1
2d320 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
2d330 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2d340 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2d350 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2d360 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20   shall register 
2d370 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20  callbacks to be 
2d380 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20  invoked for the 
2d390 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
2d3a0 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58  function named X
2d3b0 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72   with any number
2d3c0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
2d3d0 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68  *.** {H16133} Wh
2d3e0 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
2d3f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d400 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2d410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
2d420 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
2d430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2d440 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2d450 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20  on X.**         
2d460 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d   and when one im
2d470 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73  plementation has
2d480 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74   N>=0 and the ot
2d490 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a  her has N=(-1).*
2d4a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
2d4b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2d4c0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20  th a non-zero N 
2d4d0 73 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72 72  shall be preferr
2d4e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ed..**.** {H1613
2d4f0 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  6} When calls to
2d500 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d510 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2d520 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  E,...)].**      
2d530 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74      specify mult
2d540 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2d550 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2d560 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68   function X with
2d570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d580 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20   same number of 
2d590 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20  arguments N but 
2d5a0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a  with different.*
2d5b0 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64  *          encod
2d5c0 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65  ings E, then the
2d5d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d5e0 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20  where E matches 
2d5f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d600 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2d610 67 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72 65  g shall preferre
2d620 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39  d..**.** {H16139
2d630 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61  } For an aggrega
2d640 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2d650 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
2d660 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d670 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d680 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53  on(D,X,N,E,P,0,S
2d690 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a  ,L)] the finaliz
2d6a0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  er.**          f
2d6b0 75 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c 20  unction L shall 
2d6c0 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65  always be invoke
2d6d0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69  d exactly once i
2d6e0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d6f0 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20    step function 
2d700 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20  S is called one 
2d710 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2d720 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68  *.** {H16142} Wh
2d730 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
2d740 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75  s either the xFu
2d750 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63  nc or xStep func
2d760 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
2d770 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69      an applicati
2d780 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d790 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2d7a0 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  gate created.** 
2d7b0 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
2d7c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d7d0 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  tion()] or [sqli
2d7e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d7f0 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  ion16()],.**    
2d800 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61        then the a
2d810 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33  rray of [sqlite3
2d820 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20  _value] objects 
2d830 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
2d840 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20            third 
2d850 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20  parameter shall 
2d860 62 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  be [protected sq
2d870 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d880 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ects..*/.int sql
2d890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d8a0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2d8b0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2d8c0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2d8d0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2d8e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2d8f0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2d900 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2d910 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2d920 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2d930 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2d940 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2d950 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2d960 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2d970 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2d980 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2d990 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2d9a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2d9b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2d9c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2d9d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2d9e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2d9f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2da00 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2da10 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2da20 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2da30 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2da40 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2da50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2da60 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2da70 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2da80 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2da90 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
2daa0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2dab0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37  ncodings {H10267
2dac0 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31  } <S50200> <H161
2dad0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
2dae0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
2daf0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
2db00 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
2db10 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
2db20 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
2db30 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
2db40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2db50 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
2db60 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2db70 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
2db80 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2db90 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
2dba0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2dbb0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
2dbc0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
2dbd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
2dbe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2dbf0 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
2dc00 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
2dc10 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
2dc20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
2dc30 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2dc40 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
2dc50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2dc60 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
2dc70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dc80 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
2dc90 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
2dca0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
2dcb0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
2dcc0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
2dcd0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
2dce0 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
2dcf0 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
2dd00 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
2dd10 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
2dd20 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
2dd30 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
2dd40 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
2dd50 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
2dd60 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
2dd70 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2dd80 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
2dd90 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
2dda0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
2ddb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
2ddc0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
2ddd0 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
2dde0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 53 51 4c   they do..*/.SQL
2ddf0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2de00 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
2de10 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
2de20 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
2de30 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2de40 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2de50 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
2de60 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2de70 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2de80 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
2de90 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2dea0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
2deb0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2dec0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2ded0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
2dee0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
2def0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
2df00 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
2df10 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
2df20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2df30 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
2df40 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
2df50 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2df60 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
2df70 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f  lite3_int64);../
2df80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2df90 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2dfa0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2dfb0 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20  Values {H15100} 
2dfc0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
2dfd0 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
2dfe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2dff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2e000 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
2e010 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
2e020 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
2e030 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
2e040 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
2e050 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
2e060 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2e070 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
2e080 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
2e090 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
2e0a0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
2e0b0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
2e0c0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
2e0d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2e0e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2e0f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2e100 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
2e110 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
2e120 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2e130 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2e140 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
2e150 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2e160 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
2e170 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
2e180 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
2e190 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e1a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2e1b0 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2e1c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2e1d0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
2e1e0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
2e1f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2e200 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2e210 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
2e220 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
2e230 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2e240 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2e250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2e260 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
2e270 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
2e280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e290 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
2e2a0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
2e2b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2e2c0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2e2d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2e2e0 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
2e2f0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
2e300 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  ehavior..**.** T
2e310 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2e320 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
2e330 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
2e340 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2e350 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
2e360 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
2e370 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
2e380 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
2e390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e3a0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
2e3b0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
2e3c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
2e3d0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
2e3e0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
2e3f0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ber..**.** The s
2e400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e410 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
2e420 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
2e430 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
2e440 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
2e450 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2e460 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a   machine.  The.*
2e470 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2e480 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2e490 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e4a0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2e4b0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2e4c0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2e4d0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2e4e0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2e4f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2e500 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
2e510 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2e520 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2e530 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2e540 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2e550 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2e560 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2e570 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2e580 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2e590 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2e5a0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2e5b0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2e5c0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2e5d0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2e5e0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2e5f0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2e600 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2e610 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2e620 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2e630 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2e640 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2e650 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2e660 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2e670 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2e680 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2e690 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2e6a0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2e6b0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2e6c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2e6d0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
2e6e0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
2e6f0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
2e700 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
2e710 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2e720 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e730 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2e740 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
2e750 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
2e760 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
2e770 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
2e780 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
2e790 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2e7a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e7b0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
2e7c0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
2e7d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e7e0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2e7f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e800 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
2e810 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2e820 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2e830 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2e840 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
2e850 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
2e860 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
2e870 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
2e880 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  meters..**.** IN
2e890 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2e8a0 7b 48 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71  {H15103} The [sq
2e8b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2e8c0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2e8d0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2e8e0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2e8f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e900 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2e910 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a  a BLOB and then.
2e920 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2e930 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e940 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76   the converted v
2e950 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  alue..**.** {H15
2e960 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  106} The [sqlite
2e970 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29  3_value_bytes(V)
2e980 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2e990 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
2e9a0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
2e9b0 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20  tes in the BLOB 
2e9c0 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
2e9d0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
2e9e0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
2e9f0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
2ea00 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
2ea10 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2ea20 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
2ea30 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2ea40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2ea50 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20  lob(V)] or.**   
2ea60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2ea70 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a  value_text(V)]..
2ea80 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54  **.** {H15109} T
2ea90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2eaa0 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e  e_bytes16(V)] in
2eab0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2eac0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ead0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2eae0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65  in the string (e
2eaf0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
2eb00 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2eb10 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
2eb20 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
2eb30 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
2eb40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2eb50 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2eb60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   to [sqlite3_val
2eb70 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a  ue_text16(V)],.*
2eb80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2eb90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2eba0 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  be(V)], or [sqli
2ebb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2ebc0 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  le(V)]..**.** {H
2ebd0 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  15112} The [sqli
2ebe0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
2ebf0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2ec00 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2ec10 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2ec20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ec30 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2ec40 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2ec50 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
2ec60 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2ec70 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
2ec80 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  lue..**.** {H151
2ec90 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
2eca0 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69  _value_int(V)] i
2ecb0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2ecc0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2ecd0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2ece0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ecf0 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2ed00 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2ed10 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2ed20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f    returns the lo
2ed30 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74  wer 32 bits of t
2ed40 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
2ed50 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20  ** {H15118} The 
2ed60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2ed70 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61  nt64(V)] interfa
2ed80 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2ed90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2eda0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2edb0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2edc0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2edd0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2ede0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2edf0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2ee00 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2ee10 2a 20 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b  * {H15121} The [
2ee20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ee30 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  xt(V)] interface
2ee40 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2ee50 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2ee60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ee70 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2ee80 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2ee90 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ted UTF-8.**    
2eea0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2eeb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2eec0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2eed0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34  g..**.** {H15124
2eee0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2eef0 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20  alue_text16(V)] 
2ef00 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2ef10 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2ef20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2ef30 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ef40 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
2ef50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2ef60 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2ef70 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e  aligned UTF-16 n
2ef80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ef90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2efa0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
2efb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2efc0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2efd0 7b 48 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71  {H15127} The [sq
2efe0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2eff0 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61  16be(V)] interfa
2f000 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2f010 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2f020 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f030 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2f040 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2f050 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2f060 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2f070 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
2f080 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2f090 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2f0a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2f0b0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2f0c0 2a 20 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b  * {H15130} The [
2f0d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f0e0 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72  xt16le(V)] inter
2f0f0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2f100 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2f110 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f120 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2f130 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2f140 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2f150 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2f160 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ed UTF-16 little
2f170 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
2f180 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2f190 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f1a0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2f1b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20  .**.** {H15133} 
2f1c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2f1d0 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ue_type(V)] inte
2f1e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2f1f0 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
2f200 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
2f210 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2f220 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
2f230 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2f240 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
2f250 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
2f260 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
2f270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2f280 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2f290 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
2f2a0 20 7b 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73   {H15136} The [s
2f2b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2f2c0 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e  eric_type(V)] in
2f2d0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2f2e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2f2f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2f300 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f310 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20  t V into either 
2f320 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a  an integer or.**
2f330 20 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61            a floa
2f340 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2f350 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f   if it can do so
2f360 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
2f370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
2f380 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65  ormation, and re
2f390 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51  turns one of [SQ
2f3a0 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20  LITE_NULL],.**  
2f3b0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2f3c0 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2f3d0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2f3e0 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20  E_TEXT], or.**  
2f3f0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2f400 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2f410 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20  iate for the.** 
2f420 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2f430 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f440 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65  e] object V afte
2f450 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  r the conversion
2f460 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e   attempt..*/.con
2f470 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f480 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2f490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2f4a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2f4b0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2f4c0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2f4d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2f4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f4f0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2f500 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2f510 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f520 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f530 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2f540 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2f550 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2f560 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2f570 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2f580 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2f590 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f5b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f5c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f5d0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2f5e0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f5f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f600 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2f610 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2f620 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2f630 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2f640 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2f660 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f670 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2f680 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2f690 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f6a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f6b0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2f6c0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2f6d0 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c  ntext {H16210} <
2f6e0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2f6f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f700 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
2f710 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
2f720 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2f730 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74  allocate.** a st
2f740 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72  ructure for stor
2f750 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
2f760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2f770 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
2f780 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f790 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ext() routine is
2f7a0 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a   called for a.**
2f7b0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
2f7c0 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c  egate, SQLite al
2f7d0 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f  locates nBytes o
2f7e0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
2f7f0 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d   out that.** mem
2f800 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
2f810 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
2f820 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20  . On second and 
2f830 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
2f840 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
2f850 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f860 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
2f870 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2f880 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65  on index,.** the
2f890 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
2f8a0 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d  returned. The im
2f8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f8c0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
2f8d0 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74  n use.** the ret
2f8e0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
2f8f0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
2f900 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75  .**.** SQLite au
2f910 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2f920 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  s the allocated 
2f930 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20  buffer when the 
2f940 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65  aggregate.** que
2f950 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
2f960 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
2f970 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
2f980 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
2f990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2f9a0 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
2f9b0 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
2f9c0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
2f9d0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
2f9e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
2f9f0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
2fa00 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
2fa10 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2fa20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
2fa30 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2fa40 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2fa50 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2fa60 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
2fa70 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2fa80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
2fa90 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2faa0 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20  6211} The first 
2fab0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
2fac0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fad0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2fae0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
2faf0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
2fb00 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65  ance of an aggre
2fb10 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66  gate function (f
2fb20 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
2fb30 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
2fb40 65 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51  ext C) causes SQ
2fb50 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  Lite to allocate
2fb60 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
2fb70 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ry,.**          
2fb80 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79  zero that memory
2fb90 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  , and return a p
2fba0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c  ointer to the al
2fbb0 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a  located memory..
2fbc0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49  **.** {H16213} I
2fbd0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2fbe0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2fbf0 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20  rs during.**    
2fc00 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61        [sqlite3_a
2fc10 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2fc20 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20  (C,N)] then the 
2fc30 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2fc40 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31   0..**.** {H1621
2fc50 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75  5} Second and su
2fc60 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2fc70 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ions of.**      
2fc80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67      [sqlite3_agg
2fc90 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2fca0 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d  ,N)] for the sam
2fcb0 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
2fcc0 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r C.**          
2fcd0 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72  ignore the N par
2fce0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
2fcf0 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  n a pointer to t
2fd00 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
2fd10 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d      block of mem
2fd20 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
2fd30 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  the first invoca
2fd40 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tion..**.** {H16
2fd50 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20  217} The memory 
2fd60 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71  allocated by [sq
2fd70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2fd80 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73  context(C,N)] is
2fd90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
2fda0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2fdb0 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c   on the next cal
2fdc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
2fdd0 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  set()].**       
2fde0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66     or [sqlite3_f
2fdf0 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74  inalize()] for t
2fe00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2fe10 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69  tement] containi
2fe20 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ng.**          t
2fe30 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2fe40 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2fe50 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e   with context C.
2fe60 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2fe70 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fe80 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2fe90 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
2fea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2feb0 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
2fec0 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
2fed0 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  240} <S20200>.**
2fee0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2fef0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2ff00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2ff10 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2ff20 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2ff30 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2ff40 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2ff50 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2ff60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2ff70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2ff80 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2ff90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ffa0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2ffb0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2ffc0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2ffd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2ffe0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
2fff0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
30000 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
30010 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
30020 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
30030 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
30040 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30050 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
30060 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
30070 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
30080 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69  16243} The [sqli
30090 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29  te3_user_data(C)
300a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
300b0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
300c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20  e.**          P 
300d0 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65  pointer from the
300e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
300f0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
30100 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
30110 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
30120 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30130 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ion16(D,X,N,E,P,
30140 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61  F,S,L)] call tha
30150 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  t.**          re
30160 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c  gistered the SQL
30170 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
30180 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  ated with [sqlit
30190 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
301a0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
301b0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
301c0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
301d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
301e0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
301f0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
30200 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30  {H16250} <S60600
30210 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20200>.**.** 
30220 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
30230 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
30240 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30250 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
30260 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
30270 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30280 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
30290 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
302a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
302b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
302c0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
302d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
302e0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
302f0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
30300 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
30310 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
30320 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
30330 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
30340 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d  :.**.** {H16253}
30350 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
30360 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
30370 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  C)] interface re
30380 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
30390 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
303a0 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74  D pointer from t
303b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
303c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
303d0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
303e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
303f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30400 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c  ction16(D,X,N,E,
30410 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74  P,F,S,L)] call t
30420 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
30430 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53  registered the S
30440 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
30450 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c  ciated with [sql
30460 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
30470 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
30480 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
30490 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
304a0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
304b0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
304c0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
304d0 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30  ta {H16270} <S20
304e0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  200>.**.** The f
304f0 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
30500 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
30510 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
30520 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
30530 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
30540 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
30550 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
30560 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
30570 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
30580 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
30590 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
305a0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
305b0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
305c0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
305d0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
305e0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
305f0 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
30600 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
30610 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
30620 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
30630 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
30640 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
30650 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
30660 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
30670 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
30680 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
30690 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
306a0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
306b0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
306c0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
306d0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
306e0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
306f0 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
30700 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
30710 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
30720 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
30730 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
30740 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
30750 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
30760 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
30770 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
30780 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
30790 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
307a0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
307b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
307c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
307d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
307e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
307f0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
30800 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
30810 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
30820 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
30830 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
30840 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
30850 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30860 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30870 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  n. If no metadat
30880 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
30890 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
308a0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
308b0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
308c0 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
308d0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
308e0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
308f0 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
30900 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
30910 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
30920 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
30930 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
30940 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
30950 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30960 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
30970 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
30980 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
30990 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
309a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
309b0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
309c0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
309d0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
309e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
309f0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
30a00 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
30a10 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
30a20 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
30a30 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
30a40 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
30a50 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
30a60 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20  ed..** If it is 
30a70 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
30a80 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
30a90 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
30aa0 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
30ab0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
30ac0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
30ad0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
30ae0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
30af0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
30b00 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
30b10 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
30b20 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
30b30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
30b40 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
30b50 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
30b60 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
30b70 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
30b80 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
30b90 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
30ba0 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
30bb0 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
30bc0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
30bd0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
30be0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
30bf0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
30c00 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
30c10 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
30c20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
30c30 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
30c40 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
30c50 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
30c60 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
30c70 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
30c80 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
30c90 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
30ca0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
30cb0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
30cc0 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
30cd0 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
30ce0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
30cf0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30d00 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30d10 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
30d20 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
30d30 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
30d40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
30d50 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c  H16272} The [sql
30d60 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30d70 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,N)] interface
30d80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30d90 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
30da0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
30db0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e  iated with the N
30dc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
30dd0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f  .**          who
30df0 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c  se context is C,
30e00 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72   or NULL if ther
30e10 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
30e20 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20   associated.**  
30e30 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61          with tha
30e40 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
30e50 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20  ** {H16274} The 
30e60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
30e70 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
30e80 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73  nterface assigns
30e90 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20   a metadata.**  
30ea0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
30eb0 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72  P to the Nth par
30ec0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
30ed0 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  L function with 
30ee0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a  context C..**.**
30ef0 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65   {H16276} SQLite
30f00 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
30f10 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
30f20 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  th a single argu
30f30 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
30f40 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65   which is the me
30f50 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50  tadata pointer P
30f60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
30f70 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
30f80 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
30f90 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
30fa0 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73  when SQLite ceas
30fb0 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20  es to hold.**   
30fc0 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64         the metad
30fd0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ata..**.** {H162
30fe0 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65  77} SQLite cease
30ff0 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61  s to hold metada
31000 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75  ta for an SQL fu
31010 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
31020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
31030 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
31040 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68  hat parameter ch
31050 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anges..**.** {H1
31060 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69  6278} When [sqli
31070 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31080 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76  C,N,P,D)] is inv
31090 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75  oked, the destru
310a0 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctor.**         
310b0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
310c0 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74  ny prior metadat
310d0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
310e0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
310f0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
31100 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61  context C and pa
31110 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a  rameter N..**.**
31120 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65   {H16279} SQLite
31130 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72   will call destr
31140 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d  uctors for any m
31150 65 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f  etadata it is ho
31160 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  lding.**        
31170 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61    in a particula
31180 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
31190 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69  ement] S when ei
311a0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
311b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
311c0 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  S)] or [sqlite3_
311d0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20  finalize(S)] is 
311e0 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  called..*/.void 
311f0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
31200 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
31210 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
31220 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
31230 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
31240 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
31250 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
31260 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
31270 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
31280 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
31290 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
312a0 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32  r Behavior {H102
312b0 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  80} <S30100>.**.
312c0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
312d0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
312e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
312f0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
31300 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
31310 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
31320 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
31330 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31340 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
31350 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
31360 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
31370 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
31380 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
31390 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
313a0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
313b0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
313c0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
313d0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
313e0 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   The.** SQLITE_T
313f0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
31400 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
31410 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
31420 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
31430 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
31440 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
31450 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
31460 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
31470 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
31480 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
31490 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
314a0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
314b0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
314c0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
314d0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
314e0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
314f0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
31500 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
31510 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
31520 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
31530 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
31540 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
31550 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
31560 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
31570 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
31580 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
31590 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
315a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
315b0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
315c0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
315d0 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c  ction {H16400} <
315e0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
315f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
31600 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
31610 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
31620 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
31630 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
31640 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31650 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
31660 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31670 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
31680 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31690 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
316a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
316b0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
316c0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
316d0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
316e0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
316f0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
31700 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
31710 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
31720 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
31730 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
31740 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31750 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
31760 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
31770 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
31780 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
31790 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
317a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
317b0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
317c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
317d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
317e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
317f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31800 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
31810 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
31820 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
31830 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
31840 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
31850 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
31860 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
31870 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
31880 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
31890 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
318a0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
318b0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
318c0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
318d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
318e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
318f0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
31900 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
31910 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
31920 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
31930 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
31940 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
31950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
31960 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
31970 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
31980 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
31990 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
319a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
319b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
319c0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
319d0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
319e0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
319f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
31a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31a10 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
31a20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31a30 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
31a40 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
31a50 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
31a60 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
31a70 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
31a80 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
31a90 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
31aa0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
31ab0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
31ac0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31ad0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31ae0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
31af0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
31b00 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
31b10 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
31b20 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
31b30 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
31b40 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
31b50 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
31b60 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  TF-8. SQLite.** 
31b70 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
31b80 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
31b90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31ba0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
31bb0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
31bc0 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74  order.  If the t
31bd0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
31be0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
31bf0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
31c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31c10 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
31c20 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
31c30 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
31c40 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
31c50 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
31c60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
31c70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
31c80 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
31c90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31ca0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
31cb0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
31cc0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
31cd0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
31ce0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
31cf0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
31d00 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
31d10 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
31d20 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
31d30 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
31d40 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
31d50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
31d60 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
31d70 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
31d80 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
31d90 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
31da0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
31db0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
31dc0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
31dd0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
31de0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
31df0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
31e00 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
31e10 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
31e20 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
31e30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31e40 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
31e50 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
31e60 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
31e70 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
31e80 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
31e90 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
31ea0 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
31eb0 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
31ec0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
31ed0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
31ee0 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
31ef0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
31f00 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
31f10 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31f20 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
31f30 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
31f40 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
31f50 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
31f60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
31f70 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
31f80 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
31f90 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
31fa0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
31fb0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
31fc0 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f  OB is to long to
31fd0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
31fe0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31ff0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
32000 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
32010 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
32020 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
32030 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
32040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
32050 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
32060 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
32070 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
32080 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
32090 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
320a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
320b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
320c0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
320d0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
320e0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
320f0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
32100 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
32110 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
32120 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
32130 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
32140 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
32150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32160 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
32170 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
32180 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
32190 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
321a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
321b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
321c0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
321d0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
321e0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
321f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32200 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32210 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32220 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
32230 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
32240 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32250 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
32260 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
32270 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
32280 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32290 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
322a0 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
322b0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
322c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
322d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
322e0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
322f0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
32300 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
32310 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
32320 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
32330 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
32340 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
32350 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
32360 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
32370 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
32380 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
32390 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
323a0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
323b0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
323c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
323d0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
323e0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
323f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
32400 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
32410 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
32420 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
32430 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
32440 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
32450 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32460 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
32470 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
32480 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
32490 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
324a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
324b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
324c0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
324d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
324e0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
324f0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
32500 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
32510 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
32520 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
32530 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
32540 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
32560 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
32570 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32580 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
32590 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
325a0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
325b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
325c0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
325d0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
325e0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
325f0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
32600 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
32610 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
32620 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
32630 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
32640 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
32650 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
32660 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
32670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32680 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
32690 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
326a0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
326b0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
326c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
326d0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
326e0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
326f0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
32700 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
32710 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
32720 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
32730 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64  e it or call a d
32740 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69  estructor when i
32750 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
32760 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
32770 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
32780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32790 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
327a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
327b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
327c0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
327d0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
327e0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
327f0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
32800 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
32810 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
32820 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
32830 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
32840 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
32850 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
32860 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
32870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
32880 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
32890 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
328a0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
328b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
328c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
328d0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
328e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
328f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
32900 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
32910 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
32920 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
32930 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
32940 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
32950 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
32960 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
32970 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
32980 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
32990 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
329a0 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
329b0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
329c0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
329d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
329e0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
329f0 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72  t harm..** A [pr
32a00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32a10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
32a20 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
32a30 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
32a40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32a50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
32a60 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
32a70 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
32a80 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
32a90 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
32aa0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
32ab0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
32ac0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
32ad0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
32ae0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
32af0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
32b00 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
32b10 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
32b20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32b30 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
32b40 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
32b50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
32b60 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
32b70 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
32b80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ned..**.** INVAR
32b90 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
32ba0 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c  6403} The defaul
32bb0 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  t return value f
32bc0 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63  rom any SQL func
32bd0 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  tion is NULL..**
32be0 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65  .** {H16406} The
32bf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32c00 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20  _blob(C,V,N,D)] 
32c10 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32c20 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32c30 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32c40 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32c50 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69  be a BLOB that i
32c60 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  s N bytes.**    
32c70 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20        in length 
32c80 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74  and with content
32c90 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56   pointed to by V
32ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d  ..**.** {H16409}
32cb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32cc0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29  sult_double(C,V)
32cd0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32ce0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32cf0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32d00 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32d10 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e  o be the floatin
32d20 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e  g point value V.
32d30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20  .**.** {H16412} 
32d40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32d50 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29  ult_error(C,V,N)
32d60 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32d70 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
32d80 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
32d90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32da0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
32db0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
32dc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
32dd0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
32de0 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d   a UTF-8 error m
32df0 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72  essage copied fr
32e00 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a  om V up to the.*
32e10 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
32e20 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e   zero byte or un
32e30 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20  til N bytes are 
32e40 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73  read if N is pos
32e50 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  itive..**.** {H1
32e60 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6415} The [sqlit
32e70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
32e80 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  6(C,V,N)] interf
32e90 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
32ea0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
32eb0 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
32ec0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
32ed0 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
32ee0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
32ef0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
32f00 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31  ROR] and a UTF-1
32f10 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
32f20 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  der error messag
32f30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
32f40 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
32f50 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
32f60 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75   terminator or u
32f70 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20  ntil N bytes.** 
32f80 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61           are rea
32f90 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
32fa0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31  ve..**.** {H1641
32fb0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
32fc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
32fd0 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63  big(C)] interfac
32fe0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
32ff0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
33000 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
33010 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
33020 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
33030 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
33040 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
33050 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61  TOOBIG] and an a
33060 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
33070 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
33080 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71  {H16421} The [sq
33090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
330a0 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74  or_nomem(C)] int
330b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
330c0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
330d0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
330e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
330f0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
33100 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
33110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
33120 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20  LITE_NOMEM] and 
33130 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
33140 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
33150 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65  .** {H16424} The
33160 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33170 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29  _error_code(C,E)
33180 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
33190 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
331a0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
331b0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
331c0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
331d0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
331e0 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20   code E..**     
331f0 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d       The error m
33200 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75  essage text is u
33210 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
33220 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71  {H16427} The [sq
33230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
33240 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
33250 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
33260 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
33270 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
33280 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32  n C to be the 32
33290 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
332a0 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
332b0 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  430} The [sqlite
332c0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43  3_result_int64(C
332d0 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
332e0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
332f0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
33300 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
33310 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  C to be the 64-b
33320 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  it integer value
33330 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33   V..**.** {H1643
33340 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
33350 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20  result_null(C)] 
33360 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
33370 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
33380 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
33390 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
333a0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  be NULL..**.** {
333b0 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c  H16436} The [sql
333c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
333d0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
333e0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
333f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
33400 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
33410 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
33420 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  e UTF-8 string.*
33430 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20  *          V up 
33440 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
33450 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
33460 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
33470 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
33480 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
33490 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
334a0 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68  *.** {H16439} Th
334b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
334c0 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
334d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
334e0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
334f0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
33500 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
33510 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36  to be the UTF-16
33520 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33530 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
33540 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
33550 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
33560 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
33570 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
33580 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
33590 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
335a0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
335b0 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71  {H16442} The [sq
335c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
335d0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16be(C,V,N,D)] 
335e0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
335f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
33600 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
33610 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
33620 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69  be the UTF-16 bi
33630 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
33640 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
33650 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
33660 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
33670 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
33680 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
33690 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69  ytes or V if N i
336a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
336b0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54  **.** {H16445} T
336c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
336d0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
336e0 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
336f0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
33700 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
33710 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
33720 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
33730 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
33740 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
33750 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
33760 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
33770 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
33780 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
33790 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
337a0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
337b0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
337c0 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c  H16448} The [sql
337d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
337e0 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
337f0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
33800 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
33810 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
33820 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b  on C to be the [
33830 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33840 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20  te3_value].**   
33850 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e         object V.
33860 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20  .**.** {H16451} 
33870 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33880 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
33890 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
338a0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
338b0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
338c0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
338d0 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20  to be an N-byte 
338e0 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f  BLOB of all zero
338f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34  s..**.** {H16454
33900 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
33910 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61  esult_error()] a
33920 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
33930 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a  lt_error16()].**
33940 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
33950 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79  aces make a copy
33960 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20   of their error 
33970 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
33980 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  before.**       
33990 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a     returning..**
339a0 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20  .** {H16457} If 
339b0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
339c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
339d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
339e0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
339f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
33a00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
33a10 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
33a20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33a30 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
33a40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
33a50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
33a60 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
33a70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33a80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33a90 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
33aa0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53   the constant [S
33ab0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a  QLITE_STATIC].**
33ac0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e            then n
33ad0 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  o destructor is 
33ae0 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ever called on t
33af0 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64  he pointer V and
33b00 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20   SQLite.**      
33b10 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74      assumes that
33b20 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e   V is immutable.
33b30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20  .**.** {H16460} 
33b40 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
33b50 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
33b60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33b70 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
33b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33b90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33ba0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
33bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33bc0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
33bd0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33be0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33bf0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
33c00 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
33c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33c20 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
33c30 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
33c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
33c50 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
33c60 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61  then the interfa
33c70 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ces makes a copy
33c80 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
33c90 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56      content of V
33ca0 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65   and retains the
33cb0 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   copy..**.** {H1
33cc0 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64  6463} If the D d
33cd0 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
33ce0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
33cf0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
33d00 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
33d10 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
33d20 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
33d30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
33d40 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
33d50 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
33d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33d70 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
33d80 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
33d90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
33da0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
33db0 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76  ,N,D)] is some v
33dc0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a  alue other than.
33dd0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
33de0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
33df0 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53  E_STATIC] and [S
33e00 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
33e10 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
33e20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e    SQLite will in
33e30 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
33e40 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20  tor D with V as 
33e50 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
33e60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
33e70 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
33e80 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61  ed with the V va
33e90 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lue..*/.void sql
33ea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33eb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33ec0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33ed0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
33ee0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
33ef0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
33f00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33f10 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
33f20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f30 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
33f40 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
33f50 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
33f60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33f70 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
33f80 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
33f90 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
33fa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33fb0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
33fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33fd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33fe0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
33ff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34000 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34010 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
34020 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34030 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
34040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34050 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
34060 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
34070 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34080 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
34090 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
340a0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
340b0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
340c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
340d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
340e0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
340f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34100 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
34110 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34120 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34130 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
34140 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34150 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
34160 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34170 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34180 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
34190 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
341a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
341b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
341c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
341d0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
341e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
341f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
34200 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
34210 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34220 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
34230 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
34240 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
34250 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34260 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
34270 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34280 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
34290 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
342a0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
342b0 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c  ences {H16600} <
342c0 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20300>.**.** Th
342d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
342e0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
342f0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
34300 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
34310 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34320 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
34330 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34340 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
34350 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
34360 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
34370 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  nce is specified
34380 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   as a UTF-8 stri
34390 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
343a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
343b0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
343c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
343d0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
343e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f  UTF-16 string fo
343f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
34400 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20  _collation16(). 
34410 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
34420 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
34430 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
34440 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
34450 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
34460 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  ird argument may
34470 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
34480 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
34490 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
344a0 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b  TE_UTF16LE] or [
344b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
344c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
344d0 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
344e0 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
344f0 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
34500 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
34510 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
34520 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
34530 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
34540 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
34550 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig-endian, respe
34560 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20  ctively. The.** 
34570 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
34580 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51  ight also be [SQ
34590 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
345a0 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ED] to indicate 
345b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74  that.** the rout
345c0 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e  ine expects poin
345d0 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77  ters to 16-bit w
345e0 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69  ord aligned stri
345f0 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36  ngs.** of UTF-16
34600 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
34610 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  yte order of the
34620 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
34630 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
34640 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
34650 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
34660 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
34670 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
34680 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20  ment.  If it is 
34690 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68  NULL, this is th
346a0 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69  e same as deleti
346b0 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ng the collation
346c0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f  .** sequence (so
346d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
346e0 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d  not call it anym
346f0 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69  ore)..** Each ti
34700 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  me the applicati
34710 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  on supplied func
34720 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
34730 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a   it is passed.**
34740 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61   as its first pa
34750 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f  rameter a copy o
34760 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73  f the void* pass
34770 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
34780 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
34790 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
347a0 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71  ollation() or sq
347b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
347c0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  lation16()..**.*
347d0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
347e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
347f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
34800 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
34810 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
34820 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
34830 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
34840 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
34850 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
34860 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
34870 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
34880 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
34890 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
348a0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
348b0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
348c0 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69  {END}  The appli
348d0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
348e0 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
348f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
34900 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
34910 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
34920 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
34930 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
34940 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
34950 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
34960 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
34970 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
34980 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54  TRING2)..**.** T
34990 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
349a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
349b0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
349c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
349d0 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  tion().** except
349e0 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61   that it takes a
349f0 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74  n extra argument
34a00 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74   which is a dest
34a10 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68  ructor for.** th
34a20 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68  e collation.  Th
34a30 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
34a40 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
34a50 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  collation is.** 
34a60 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73  destroyed and is
34a70 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
34a80 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
34a90 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69  ameter void* poi
34aa0 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73  nter.** of the s
34ab0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34ac0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  llation_v2()..**
34ad0 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20   Collations are 
34ae0 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74  destroyed when t
34af0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
34b00 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c  en by later call
34b10 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c  s to the.** coll
34b20 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
34b30 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
34b40 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34b50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
34b60 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  osed.** using [s
34b70 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
34b80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34b90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33  S:.**.** {H16603
34ba0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
34bb0 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  all to the.**   
34bc0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
34bd0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34be0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
34bf0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  ] interface.**  
34c00 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
34c10 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20  s function F as 
34c20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
34c30 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a  unction used to.
34c40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c  **          impl
34c50 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  ement collation 
34c60 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  X on the [databa
34c70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
34c80 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
34c90 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e   databases havin
34ca0 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a  g encoding E..**
34cb0 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c  .** {H16604} SQL
34cc0 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20  ite understands 
34cd0 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
34ce0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
34cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34d00 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
34d10 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a  E,P,F,D)] as a z
34d20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
34d30 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
34d40 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68   string in which
34d50 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64   case is ignored
34d60 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61   for ASCII chara
34d70 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20  cters and.**    
34d80 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69        is signifi
34d90 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43  cant for non-ASC
34da0 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  II characters..*
34db0 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75  *.** {H16606} Su
34dc0 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74  ccessive calls t
34dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
34de0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
34df0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
34e00 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
34e10 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f  e same values fo
34e20 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f  r B, X, and E, o
34e30 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61  verride prior va
34e40 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
34e50 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e   of P, F, and D.
34e60 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20  .**.** {H16609} 
34e70 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
34e80 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r D in [sqlite3_
34e90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34ea0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
34eb0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
34ec0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69   not NULL then i
34ed0 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  t is called with
34ee0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
34ef0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
34f00 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34f10 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62  ion is dropped b
34f20 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  y SQLite..**.** 
34f30 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61  {H16612} A colla
34f40 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34f50 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74   dropped when it
34f60 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   is overloaded..
34f70 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41  **.** {H16615} A
34f80 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34f90 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77  ion is dropped w
34fa0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
34fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
34fc0 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65          is close
34fd0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34fe0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
34ff0 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f   {H16618} The po
35000 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69  inter P in [sqli
35010 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35020 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
35030 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
35040 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f    is passed thro
35050 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
35060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35070 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20  e comparison.** 
35080 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
35090 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73  n F for all subs
350a0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
350b0 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b  ns of F..**.** {
350c0 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74  H16621} A call t
350d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
350e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c  e_collation(B,X,
350f0 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74  E,P,F)] is exact
35100 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ly.**          t
35110 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c  he same as a cal
35120 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
35130 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35140 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20  2()] with.**    
35150 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70        the same p
35160 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20  arameters and a 
35170 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e  NULL destructor.
35180 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20  .**.** {H16624} 
35190 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c  Following a [sql
351a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
351b0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
351c0 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,F,D)],.**      
351d0 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20      SQLite uses 
351e0 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
351f0 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c  unction F for al
35200 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f  l text compariso
35210 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  n.**          op
35220 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
35230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35240 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20  tion] B on text 
35250 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20  values that.**  
35260 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20          use the 
35270 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
35280 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a  ce named X..**.*
35290 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b  * {H16627} The [
352a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
352b0 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45  ollation16(B,X,E
352c0 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65  ,P,F)] works the
352d0 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
352e0 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72    as [sqlite3_cr
352f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42  eate_collation(B
35300 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70  ,X,E,P,F)] excep
35310 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  t that the.**   
35320 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e         collation
35330 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72   name X is under
35340 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20  stood as UTF-16 
35350 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
35360 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
35370 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
35380 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30  8..**.** {H16630
35390 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  } When multiple 
353a0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
353b0 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
353c0 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a  le for the same.
353d0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
353e0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20  ating sequence, 
353f0 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74  SQLite chooses t
35400 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78  he one whose tex
35410 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20  t encoding.**   
35420 20 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20         requires 
35430 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
35440 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66   of conversion f
35450 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a  rom the default.
35460 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
35470 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
35480 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e   database..*/.in
35490 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
354a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
354b0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
354c0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
354d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
354e0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
354f0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
35500 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
35510 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
35520 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
35530 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35540 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
35550 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
35560 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
35570 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
35580 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
35590 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
355a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
355b0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
355c0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
355d0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
355e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
355f0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
35600 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
35610 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
35620 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
35630 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
35640 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
35650 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
35660 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
35670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
35680 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
35690 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30  Callbacks {H1670
356a0 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S20300>.**.*
356b0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
356c0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
356d0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
356e0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
356f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
35700 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
35710 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
35720 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
35730 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
35740 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35750 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c  ction] to be cal
35760 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
35770 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
35780 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
35790 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
357a0 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  ** If the functi
357b0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
357c0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
357d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
357e0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
357f0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
35800 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
35810 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
35820 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
35830 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
35840 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37   in UTF-8. {H167
35850 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63  03} If sqlite3_c
35860 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
35870 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
35880 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
35890 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
358a0 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
358b0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
358c0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
358d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
358e0 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20  es any existing 
358f0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
35900 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
35910 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
35920 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35930 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
35940 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
35950 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
35960 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35970 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
35980 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35990 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
359a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
359b0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
359c0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
359d0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
359e0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
359f0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
35a00 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
35a10 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
35a20 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
35a30 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
35a40 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
35a50 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
35a60 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
35a70 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
35a80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35a90 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
35aa0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
35ab0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
35ac0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
35ad0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35ae0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
35af0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
35b00 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
35b10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35b20 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
35b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35b40 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
35b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
35b60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
35b70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
35b80 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
35b90 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66  6702} A successf
35ba0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
35bb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
35bc0 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20  eded(D,P,F)].** 
35bd0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
35be0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35bf0 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20  eeded16(D,P,F)] 
35c00 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20  causes.**       
35c10 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
35c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
35c30 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63  o invoke callbac
35c40 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a  k F with first.*
35c50 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
35c60 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20  eter P whenever 
35c70 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61  it needs a compa
35c80 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66  rison function f
35c90 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  or a.**         
35ca0 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
35cb0 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73  nce that it does
35cc0 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e   not know about.
35cd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20  .**.** {H16704} 
35ce0 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20  Each successful 
35cf0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35d00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35d10 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  d()] or.**      
35d20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
35d30 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35d40 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
35d50 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74   callback regist
35d60 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
35d70 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
35d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35d90 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  n] by prior call
35da0 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20  s to either.**  
35db0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
35dc0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36  e..**.** {H16706
35dd0 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  } The name of th
35de0 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c  e requested coll
35df0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  ating function p
35e00 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  assed in the.** 
35e10 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72           4th par
35e20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
35e30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46  llback is in UTF
35e40 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  -8 if the callba
35e50 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ck.**          w
35e60 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  as registered us
35e70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
35e80 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
35e90 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
35ea0 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61   is in UTF-16 na
35eb0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
35ec0 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  if the callback 
35ed0 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
35ee0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
35ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
35f00 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
35f10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35f20 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35f30 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
35f40 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
35f50 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
35f60 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
35f70 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
35f80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
35f90 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
35fa0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
35fb0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
35fc0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
35fd0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
35fe0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
35ff0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
36000 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
36010 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
36020 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
36030 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
36040 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
36050 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
36060 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36070 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36080 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36090 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
360a0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
360b0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
360c0 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
360d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
360e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
360f0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
36100 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
36110 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
36120 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
36130 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
36140 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
36150 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
36160 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
36170 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
36180 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
36190 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
361a0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
361b0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
361c0 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
361d0 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
361e0 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
361f0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
36200 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
36210 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
36220 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
36230 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
36240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
36250 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
36260 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36270 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
36280 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
36290 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
362a0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
362b0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
362c0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
362d0 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
362e0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
362f0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48   A Short Time {H
36300 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a  10530} <S40410>.
36310 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36320 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
36330 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
36340 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
36350 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
36360 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
36370 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
36380 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
36390 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
363a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
363b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
363c0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
363d0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
363e0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
363f0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
36400 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
36410 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
36420 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
36430 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
36440 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
36450 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
36460 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
36470 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
36480 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
36490 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
364a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rned..**.** SQLi
364b0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
364c0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
364d0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
364e0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
364f0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
36500 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
36510 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ct..**.** INVARI
36520 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
36530 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  533} The [sqlite
36540 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65  3_sleep(M)] inte
36550 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68  rface invokes th
36560 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20  e xSleep.**     
36570 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74       method of t
36580 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
36590 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20  te3_vfs|VFS] in 
365a0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  order to.**     
365b0 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65       suspend exe
365c0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
365d0 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72  rrent thread for
365e0 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20   at least.**    
365f0 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63        M millisec
36600 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  onds..**.** {H10
36610 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  536} The [sqlite
36620 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65  3_sleep(M)] inte
36630 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
36640 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
36650 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63          millisec
36660 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
36670 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64  tually requested
36680 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   of the operatin
36690 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79  g.**          sy
366a0 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68  stem, which migh
366b0 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
366c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d   the parameter M
366d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
366e0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
366f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
36700 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
36710 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
36720 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30  ry Files {H10310
36730 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
36740 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
36750 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
36760 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
36770 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
36780 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
36790 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
367a0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
367b0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
367c0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
367d0 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  y SQLite will be
367e0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
367f0 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74  directory.  If t
36800 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
36810 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
36820 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
36830 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
36840 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
36850 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
36860 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
36870 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
36880 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20   safe to modify 
36890 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e  this variable on
368a0 63 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  ce a [database c
368b0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61  onnection].** ha
368c0 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20  s been opened.  
368d0 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
368e0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
368f0 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
36900 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
36910 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
36920 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
36930 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
36940 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
36950 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e  ave been call an
36960 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  d remain unchang
36970 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ed thereafter..*
36980 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
36990 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
369a0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
369b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
369c0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
369d0 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30  mit Mode {H12930
369e0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S60200>.** KE
369f0 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
36a00 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
36a10 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
36a20 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
36a30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
36a40 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
36a50 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
36a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36a70 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
36a80 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
36a90 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
36aa0 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  vely.  Autocommi
36ab0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
36ac0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f  default..** Auto
36ad0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
36ae0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
36af0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
36b00 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
36b10 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
36b20 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
36b30 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
36b40 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
36b50 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
36b60 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
36b70 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
36b80 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
36b90 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72  transaction (err
36ba0 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
36bb0 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
36bc0 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20  LITE_IOERR],.** 
36bd0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
36be0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
36bf0 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
36c00 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
36c10 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
36c20 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
36c30 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
36c40 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
36c50 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
36c60 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61  whether SQLite a
36c70 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
36c80 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
36c90 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
36ca0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
36cb0 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
36cc0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
36cd0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
36ce0 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  931} The [sqlite
36cf0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
36d00 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (D)] interface r
36d10 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
36d20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  or.**          z
36d30 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61  ero if the [data
36d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36d50 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20   D is or is not 
36d60 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a  in autocommit.**
36d70 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20            mode, 
36d80 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
36d90 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41 75 74  .** {H12932} Aut
36da0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
36db0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
36dc0 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20 41 75  *.** {H12933} Au
36dd0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
36de0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 73   disabled by a s
36df0 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e  uccessful [BEGIN
36e00 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  ] statement..**.
36e10 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41 75 74 6f  ** {H12934} Auto
36e20 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65  commit mode is e
36e30 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  nabled by a succ
36e40 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20  essful [COMMIT] 
36e50 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a  or [ROLLBACK].**
36e60 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
36e70 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ent..**.** ASSUM
36e80 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
36e90 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65  12936} If anothe
36ea0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
36eb0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
36ec0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
36ed0 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20  tabase.**       
36ee0 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68     connection wh
36ef0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
36f00 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
36f10 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
36f20 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ue.**          i
36f30 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
36f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
36f50 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
36f60 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
36f70 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
36f80 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
36f90 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
36fa0 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d  atement {H13120}
36fb0 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60600>.**.** 
36fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
36fd0 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
36fe0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
36ff0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37000 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
37010 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
37020 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
37030 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61 62 61  ngs.  The databa
37040 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e  se handle return
37050 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33  ed by.** sqlite3
37060 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
37070 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
37080 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73 20  handle that was 
37090 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
370a0 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
370b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
370c0 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
370d0 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
370e0 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
370f0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
37100 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
37110 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e   place..**.** IN
37120 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
37130 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71  {H13123} The [sq
37140 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
37150 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
37160 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
37170 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
37180 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37190 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  nection] associa
371a0 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ted with the.** 
371b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
371c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
371d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
371e0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
371f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
37200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37210 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
37220 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37230 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30   {H13140} <S6060
37240 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
37250 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37260 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37270 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
37280 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
37290 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
372a0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
372b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
372c0 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74  on] pDb.  If pSt
372d0 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
372e0 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
372f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
37300 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
37310 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37320 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
37330 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
37340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
37350 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61  Db.  If no prepa
37360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
37370 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
37380 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
37390 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
373a0 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
373b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
373c0 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49 66 20  .** {H13143} If 
373d0 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  D is a [database
373e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
373f0 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d  t holds one or m
37400 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
37410 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65  unfinalized [pre
37420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
37430 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c  ] and S is a NUL
37440 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20  L pointer,.**   
37450 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
37460 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
37470 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  , S)] routine sh
37480 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69  all return a poi
37490 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
374a0 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70   to one of the p
374b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
374c0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
374d0 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  th D..**.** {H13
374e0 31 34 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b  146} If D is a [
374f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37500 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  ion] that holds 
37510 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a  no unfinalized.*
37520 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
37530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
37540 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c   and S is a NULL
37550 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a   pointer, then.*
37560 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37570 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
37580 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
37590 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  ll return a NULL
375a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
375b0 7b 48 31 33 31 34 39 7d 20 49 66 20 53 20 69 73  {H13149} If S is
375c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
375d0 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b  tement] in the [
375e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
375f0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
37600 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20     and S is not 
37610 74 68 65 20 6c 61 73 74 20 70 72 65 70 61 72 65  the last prepare
37620 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44  d statement in D
37630 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
37640 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
37650 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
37660 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
37670 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  n a pointer.**  
37680 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e          to the n
37690 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
376a0 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66 74 65  tement in D afte
376b0 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  r S..**.** {H131
376c0 35 32 7d 20 49 66 20 53 20 69 73 20 74 68 65 20  52} If S is the 
376d0 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 20 73  last [prepared s
376e0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65  tatement] in the
376f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
37700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37710 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20 5b 73  n] D then the [s
37720 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
37730 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20  (D, S)].**      
37740 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c      routine shal
37750 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  l return a NULL 
37760 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  pointer..**.** A
37770 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
37780 2a 20 7b 41 31 33 31 35 34 7d 20 54 68 65 20 5b  * {A13154} The [
37790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
377a0 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
377b0 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20  n a call to.**  
377c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
377d0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
377e0 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
377f0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
37800 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e  **          conn
37810 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
37820 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
37830 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
37840 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
37850 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
37860 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
37870 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
37880 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
37890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
378a0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
378b0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
378c0 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d  llbacks {H12950}
378d0 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
378e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
378f0 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
37900 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
37910 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
37920 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
37930 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
37940 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
37950 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
37960 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
37970 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
37980 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
37990 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
379a0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
379b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
379c0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
379d0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
379e0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
379f0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
37a00 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
37a10 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
37a20 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
37a30 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
37a40 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
37a50 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
37a60 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
37a70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
37a80 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
37a90 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
37aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
37ab0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
37ac0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
37ad0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
37ae0 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
37af0 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  k..** If the cal
37b00 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
37b10 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
37b20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
37b30 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
37b40 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
37b50 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
37b60 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  k..**.** If anot
37b70 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
37b80 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
37b90 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70  stered, its.** p
37ba0 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74  Arg value is ret
37bb0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
37bc0 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
37bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ed..**.** The ca
37be0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
37bf0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
37c00 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
37c10 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
37c20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37c30 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
37c40 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
37c50 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
37c60 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
37c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37c80 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
37c90 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
37ca0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
37cb0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
37cc0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
37cd0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
37ce0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
37cf0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
37d00 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
37d10 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
37d20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
37d30 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
37d40 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
37d50 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
37d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37d70 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
37d80 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
37d90 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
37da0 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ph..**.** Regist
37db0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
37dc0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
37dd0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
37de0 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
37df0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
37e00 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
37e10 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
37e20 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
37e30 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
37e40 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
37e50 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
37e60 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
37e70 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
37e80 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
37e90 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
37ea0 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
37eb0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
37ec0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
37ed0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
37ee0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
37ef0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
37f00 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
37f10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37f20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
37f30 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
37f40 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
37f50 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
37f60 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
37f70 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
37f80 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
37f90 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
37fa0 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
37fb0 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
37fc0 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o>.**.** INVARIA
37fd0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  NTS:.**.** {H129
37fe0 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
37ff0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
38000 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
38010 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
38020 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
38030 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
38040 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
38050 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
38060 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
38070 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
38080 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61  mmits on the [da
38090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
380a0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
380b0 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  952} The [sqlite
380c0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
380d0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
380e0 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
380f0 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
38100 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76     from the prev
38110 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
38120 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
38130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
38140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
38150 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73  NULL on the firs
38160 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72  t call for a par
38170 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
38180 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
38190 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20 45 61  *.** {H12953} Ea
381a0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
381b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
381c0 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
381d0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
381e0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
381f0 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
38200 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d  ..**.** {H12954}
38210 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
38220 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
38230 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
38240 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
38250 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
38260 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
38270 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64  back is canceled
38280 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
38290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
382a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
382b0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
382c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35  ts..**.** {H1295
382d0 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
382e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
382f0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
38300 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
38310 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
38320 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
38330 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ack..**.** {H129
38340 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
38350 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
38360 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
38370 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
38380 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
38390 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
383a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
383b0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
383c0 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
383d0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
383e0 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68  rolls back on th
383f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38400 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
38410 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20 5b 73   {H12962} The [s
38420 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
38430 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
38440 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
38450 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
38460 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
38470 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
38480 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a   with the same.*
38490 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
384a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
384b0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74   D, or NULL on t
384c0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
384d0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
384e0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
384f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
38500 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d  ..**.** {H12963}
38510 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
38520 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
38530 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
38540 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
38550 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
38560 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
38570 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  calls..**.** {H1
38580 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61  2964} If the F a
38590 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
385a0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
385b0 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c  k(D,F,P)] is NUL
385c0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
385d0 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20  en the rollback 
385e0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
385f0 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f   canceled and no
38600 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
38610 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
38620 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
38630 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a  ion rolls back..
38640 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
38650 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
38660 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
38670 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
38680 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
38690 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
386a0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
386b0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
386c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
386d0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
386e0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
386f0 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30   {H12970} <S6040
38700 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
38710 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
38720 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
38730 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
38740 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
38750 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
38760 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
38770 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
38780 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
38790 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
387a0 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
387b0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
387c0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
387d0 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
387e0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
387f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
38800 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
38810 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
38820 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
38830 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
38840 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
38850 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
38860 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
38870 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
38880 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61  a.** row is upda
38890 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
388a0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65   deleted..** The
388b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
388c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callba