/ Hex Artifact Content
Login

Artifact 7da6a0d39221affca458b4ba305be3eb1590bb8e:


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 37 20 32 30 30 38 2f 30  n,v 1.397 2008/0
05f0: 39 2f 30 32 20 32 31 3a 33 35 3a 30 33 20 64 72  9/02 21:35:03 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 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
11b20 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68 65  .** {H12311} The
11b30 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
11b40 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20 66  andler(D,C,A)] f
11b50 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
11b60 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  place.**        
11b70 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20    busy callback 
11b80 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
11b90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
11ba0 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ith a new.**    
11bb0 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73 79        a new busy
11bc0 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61   handler C and a
11bd0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
11be0 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a  pointer A..**.**
11bf0 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79 20   {H12312} Newly 
11c00 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73  created [databas
11c10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
11c20 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73 79  hall have a busy
11c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
11c40 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a  dler of NULL..**
11c50 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68 65  .** {H12314} Whe
11c60 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b 64  n two or more [d
11c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11c80 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a 20  ons] share a.** 
11c90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
11ca0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
11cb0 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63  cache | common c
11cc0 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  ache],.**       
11cd0 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64     the busy hand
11ce0 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  ler for the data
11cf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11d00 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a  currently using.
11d10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
11d20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20 69  cache shall be i
11d30 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
11d40 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73  cache encounters
11d50 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b   a lock..**.** {
11d60 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73  H12316} If a bus
11d70 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
11d80 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ck returns zero,
11d90 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65   then the SQLite
11da0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
11db0 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f 76         that prov
11dc0 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67  oked the locking
11dd0 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74   event shall ret
11de0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
11df0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 38  ]..**.** {H12318
11e00 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20 69  } SQLite shall i
11e10 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20  nvokes the busy 
11e20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f  handler with two
11e30 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68   arguments which
11e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
11e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
11e60 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
11e70 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
11e80 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
11e90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
11ea0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
11eb0 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
11ec0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
11ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
11ee0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
11ef0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
11f00 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
11f10 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53   event..**.** AS
11f20 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
11f30 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73 79   {A12319} A busy
11f40 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
11f50 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
11f60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
11f70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
11f80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11f90 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
11fa0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11fb0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
11fc0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
11fd0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
11fe0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
11ff0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
12000 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
12010 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
12020 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
12030 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
12040 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
12050 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
12060 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
12070 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
12080 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
12090 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
120a0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
120b0 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
120c0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
120d0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
120e0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
120f0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
12100 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
12110 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32  ccumulated. {H12
12120 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
12130 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
12140 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
12150 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
12160 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
12170 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
12180 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
12190 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
121a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
121b0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
121c0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
121d0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
121e0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
121f0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
12200 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
12210 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
12220 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
12230 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
12240 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
12250 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
12260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12270 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
12280 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
12290 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
122a0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
122b0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
122c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
122d0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
122e0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
122f0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
12300 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
12310 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
12320 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
12330 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68 65  .** {H12341} The
12340 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
12350 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69  imeout()] functi
12360 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64  on shall overrid
12370 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20  e any prior.**  
12380 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
12390 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
123a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
123b0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
123c0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
123d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
123e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
123f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  n]..**.** {H1234
12400 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  3} If the 2nd pa
12410 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
12420 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
12430 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ()] is less than
12440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
12450 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74  equal to zero, t
12460 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e  hen the busy han
12470 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63 6c  dler shall be cl
12480 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a  eared so that.**
12490 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75            all su
124a0 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67  bsequent locking
124b0 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74   events immediat
124c0 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ely return [SQLI
124d0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
124e0 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68 65 20  {H12344} If the 
124f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
12500 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
12510 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70  imeout()] is a p
12520 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  ositive.**      
12530 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68      number N, th
12540 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  en a busy handle
12550 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20 74  r shall be set t
12560 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20 63  hat repeatedly c
12570 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  alls.**         
12580 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
12590 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71 6c  thod in the [sql
125a0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20 69  ite3_vfs | VFS i
125b0 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c 0a  nterface] until.
125c0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69 74 68  **          eith
125d0 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65 61  er the lock clea
125e0 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  rs or until the 
125f0 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70  cumulative sleep
12600 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   time.**        
12610 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20    reported back 
12620 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63 65  by xSleep() exce
12630 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e  eds N millisecon
12640 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
12650 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
12660 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
12670 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12680 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
12690 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
126a0 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31  ning Queries {H1
126b0 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  2370} <S10000>.*
126c0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
126d0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
126e0 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
126f0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
12700 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
12710 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
12720 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
12730 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
12740 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
12750 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
12760 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
12770 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
12780 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
12790 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
127a0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
127b0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
127c0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
127d0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
127e0 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
127f0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
12800 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
12810 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
12820 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
12830 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
12840 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
12850 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
12860 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
12870 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
12880 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
12890 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
128a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
128b0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
128c0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
128d0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
128e0 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
128f0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
12900 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
12910 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
12920 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
12930 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
12940 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
12950 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
12960 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
12970 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
12980 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
12990 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
129a0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
129b0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
129c0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
129d0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
129e0 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
129f0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
12a00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
12a10 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
12a20 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
12a30 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
12a40 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
12a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12a60 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
12a70 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
12a80 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
12a90 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
12aa0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
12ab0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
12ac0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
12ad0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
12ae0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
12af0 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d  **.** As an exam
12b00 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
12b10 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
12b20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
12b30 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
12b40 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
12b50 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b60 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
12b70 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
12b80 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
12b90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
12ba0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
12bb0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
12bc0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
12bd0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
12be0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
12bf0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12c00 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
12c10 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
12c20 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
12c30 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
12c40 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
12c50 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
12c60 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
12c70 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
12c80 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
12c90 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
12ca0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
12cb0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
12cc0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
12cd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
12ce0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
12cf0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
12d00 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
12d10 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
12d20 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
12d30 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12d40 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
12d50 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12d60 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
12d70 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
12d80 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
12d90 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
12da0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
12db0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
12dc0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12dd0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
12de0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12df0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
12e00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12e10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
12e20 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
12e30 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
12e40 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
12e50 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
12e60 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
12e70 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
12e80 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
12e90 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
12ea0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
12eb0 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75  ameter.  It retu
12ec0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
12ed0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
12ee0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
12ef0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
12f00 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
12f10 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
12f20 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  n has finished u
12f30 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c  sing the result,
12f40 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61   it should.** pa
12f50 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ss the pointer t
12f60 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  o the result tab
12f70 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  le to sqlite3_fr
12f80 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
12f90 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
12fa0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
12fb0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
12fc0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
12fd0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
12fe0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
12ff0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
13000 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13010 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
13020 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
13030 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
13040 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
13050 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
13060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
13070 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
13080 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
13090 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
130a0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
130b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
130c0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
130d0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
130e0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
130f0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
13100 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
13110 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
13120 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
13130 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
13140 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
13150 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
13160 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
13170 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
13180 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
13190 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
131a0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
131b0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
131c0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
131d0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
131e0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
131f0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
13200 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
13210 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
13220 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
13230 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
13240 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
13250 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
13260 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  sg()]..**.** INV
13270 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
13280 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71  H12371} If a [sq
13290 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
132a0 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72  )] fails a memor
132b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  y allocation, th
132c0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  en.**          i
132d0 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68 65  t shall free the
132e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e   result table un
132f0 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e  der construction
13300 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 20  , abort the.**  
13310 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e          query in
13320 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 61   process, skip a
13330 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75  ny subsequent qu
13340 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a 2a  eries, set the.*
13350 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a 52  *          *pazR
13360 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69  esult output poi
13370 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64  nter to NULL and
13380 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13390 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  NOMEM]..**.** {H
133a0 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70 6e  12373} If the pn
133b0 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72  Column parameter
133c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
133d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
133e0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
133f0 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
13400 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
13410 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
13420 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
13430 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 20            write 
13440 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
13450 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
13460 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
13470 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
13480 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e   into *pnColumn.
13490 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d 20  .**.** {H12374} 
134a0 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61 72  If the pnRow par
134b0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
134c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
134d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
134e0 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73          then a s
134f0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
13500 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
13510 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68  _get_table()] sh
13520 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
13530 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65  writes the numbe
13540 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65  r of rows in the
13550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
13560 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
13570 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77  uery into *pnRow
13580 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36 7d  ..**.** {H12376}
13590 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
135a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
135b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
135c0 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73 0a  ] that computes.
135d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72 6f  **          N ro
135e0 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69 74  ws of result wit
135f0 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 20  h C columns per 
13600 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 2a  row shall make *
13610 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 20  pazResult.**    
13620 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 61        point to a
13630 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
13640 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 73  ers to (N+1)*C s
13650 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68 65  trings where the
13660 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
13670 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72 65     C strings are
13680 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73   column names as
13690 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
136a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
136b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
136c0 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74 20  )] and the rest 
136d0 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c  are column resul
136e0 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  t values.**     
136f0 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
13700 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
13710 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
13720 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20 76  * {H12379} The v
13730 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61 7a  alues in the paz
13740 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65 74  Result array ret
13750 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
13760 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a  3_get_table()].*
13770 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
13780 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e   remain valid un
13790 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b  til cleared by [
137a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
137b0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  le()]..**.** {H1
137c0 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 72  2382} When an er
137d0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
137e0 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  g evaluation of 
137f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
13800 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
13810 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73    the function s
13820 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73  hall set *pazRes
13830 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 69  ult to NULL, wri
13840 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  te an error mess
13850 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  age.**          
13860 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
13870 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
13880 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61  e3_malloc()], ma
13890 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  ke.**          *
138a0 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 20  *pzErrmsg point 
138b0 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d 65  to that error me
138c0 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75 72  ssage, and retur
138d0 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n a.**          
138e0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
138f0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
13900 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
13910 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
13920 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
13930 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
13940 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
13950 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
13960 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
13970 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
13980 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
13990 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
139a0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
139b0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
139c0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
139d0 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
139e0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
139f0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
13a00 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
13a10 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
13a20 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
13a30 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
13a40 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
13a50 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
13a60 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
13a70 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
13a80 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
13a90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
13aa0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
13ab0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
13ac0 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30  s {H17400} <S700
13ad0 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  00><S20000>.**.*
13ae0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
13af0 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20   are workalikes 
13b00 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
13b10 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
13b20 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
13b30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
13b40 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rary..**.** The 
13b50 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
13b60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
13b70 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
13b80 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
13b90 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
13ba0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
13bb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
13bc0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
13bd0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
13be0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
13bf0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
13c00 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
13c10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
13c20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
13c30 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
13c40 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
13c50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
13c60 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
13c70 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
13c80 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
13c90 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
13ca0 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69  g..**.** In sqli
13cb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
13cc0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
13cd0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
13ce0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
13cf0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
13d00 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
13d10 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
13d20 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
13d30 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
13d40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
13d50 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
13d60 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
13d70 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
13d80 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
13d90 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
13da0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
13db0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
13dc0 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69  snprintf().  Thi
13dd0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
13de0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
13df0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
13e00 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
13e10 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
13e20 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
13e30 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74    Note also that
13e40 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
13e50 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
13e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
13e70 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
13e80 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
13e90 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
13ea0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
13eb0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20  nto the buffer. 
13ec0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
13ed0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13ee0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
13ef0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
13f00 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
13f10 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
13f20 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
13f30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13f40 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
13f50 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
13f60 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
13f70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
13f80 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20  *.** As long as 
13f90 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
13fa0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
13fb0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
13fc0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
13fd0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
13fe0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
13ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14000 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
14010 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
14020 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
14030 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
14040 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
14050 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
14060 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
14070 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
14080 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
14090 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
140a0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
140b0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
140c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
140d0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
140e0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
140f0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
14100 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
14110 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
14120 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
14130 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
14140 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
14150 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
14160 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
14170 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
14180 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
14190 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
141a0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
141b0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
141c0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
141d0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
141e0 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
141f0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
14200 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
14210 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
14220 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
14230 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
14240 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
14250 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
14260 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
14270 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
14280 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
14290 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
142a0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
142b0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
142c0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
142d0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
142e0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
142f0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
14300 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
14310 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
14320 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
14330 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14340 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
14350 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
14360 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
14370 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14380 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
14390 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
143a0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
143b0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
143c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
143d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
143e0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
143f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
14400 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
14410 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
14420 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
14430 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
14440 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
14450 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
14460 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
14470 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
14480 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
14490 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
144a0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
144b0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
144c0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
144d0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
144e0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
144f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14500 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14510 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
14520 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
14530 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
14540 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
14550 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
14560 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
14570 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
14580 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
14590 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
145a0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
145b0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
145c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
145d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
145e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
145f0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
14600 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
14610 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14620 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
14630 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
14640 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
14650 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
14660 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
14670 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
14680 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
14690 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
146a0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
146b0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
146c0 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
146d0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
146e0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
146f0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
14700 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
14710 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
14720 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
14730 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
14740 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
14750 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
14760 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
14770 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
14780 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
14790 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
147a0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
147b0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
147c0 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c   %Q option.  So,
147d0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
147e0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
147f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
14800 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
14810 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
14820 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
14830 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
14840 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
14850 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
14860 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
14870 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
14880 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
14890 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
148a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
148b0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
148c0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
148d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
148e0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
148f0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
14900 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
14910 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
14920 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20  .**.** The "%z" 
14930 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
14940 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
14950 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74  like "%s" with t
14960 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
14970 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
14980 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
14990 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
149a0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
149b0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
149c0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
149d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
149e0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e  . {END}.**.** IN
149f0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14a00 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73  {H17403}  The [s
14a10 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
14a20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  ] and [sqlite3_v
14a30 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  mprintf()] inter
14a40 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  faces.**        
14a50 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72     return either
14a60 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
14a70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14a80 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20  -8 strings held 
14a90 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  in.**           
14aa0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
14ab0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
14ac0 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20  lloc()] or NULL 
14ad0 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20  pointers if.**  
14ae0 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20           a call 
14af0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14b00 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a  oc()] fails..**.
14b10 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68 65  ** {H17406}  The
14b20 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
14b30 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
14b40 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65  writes a zero-te
14b50 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
14b60 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
14b70 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  ng into the buff
14b80 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  er pointed to by
14b90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14ba0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
14bb0 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74     provided that
14bc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14bd0 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20  eter is greater 
14be0 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  than zero..**.**
14bf0 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20 5b   {H17407}  The [
14c00 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14c10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  ()] interface do
14c20 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f  es not write slo
14c30 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ts of.**        
14c40 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75     its output bu
14c50 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64  ffer (the second
14c60 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73   parameter) outs
14c70 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a  ide the range.**
14c80 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20             of 0 
14c90 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65  through N-1 (whe
14ca0 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73  re N is the firs
14cb0 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
14cc0 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64            regard
14cd0 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67  less of the leng
14ce0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
14cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
14d00 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66  quested by the f
14d10 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74  ormat specificat
14d20 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  ion..*/.char *sq
14d30 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
14d40 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
14d50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
14d60 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
14d70 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
14d80 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
14d90 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
14da0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
14db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14dc0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
14dd0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b  tion Subsystem {
14de0 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e  H17300} <S20000>
14df0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
14e00 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65  e core  uses the
14e10 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
14e20 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
14e30 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
14e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14e50 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
14e60 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
14e70 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
14e80 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
14e90 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
14ea0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
14eb0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
14ec0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
14ed0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
14ee0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
14ef0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
14f00 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ons..**.** The s
14f10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14f20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
14f30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
14f40 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
14f50 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
14f60 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
14f70 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
14f80 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71  ameter..** If sq
14f90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
14fa0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
14fb0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
14fc0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
14fd0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
14fe0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65  pointer.  If the
14ff0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
15000 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
15010 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
15020 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
15030 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
15040 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
15050 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43  pointer..**.** C
15060 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
15070 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
15080 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
15090 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
150a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
150b0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
150c0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
150d0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
150e0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
150f0 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71   reused.  The sq
15100 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
15110 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
15120 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
15130 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
15140 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
15150 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
15160 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
15170 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
15180 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
15190 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
151a0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
151b0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
151c0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
151d0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
151e0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
151f0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
15200 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
15210 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
15220 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
15230 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
15240 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
15250 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
15260 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
15270 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
15280 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
15290 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
152a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
152b0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
152c0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
152d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
152e0 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a  lite3_free()..**
152f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15300 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
15310 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
15320 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
15330 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
15340 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
15350 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
15360 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
15370 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
15380 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
15390 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
153a0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
153b0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
153c0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
153d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
153e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
153f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
15400 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
15410 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
15420 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
15430 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
15440 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
15450 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15460 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15470 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
15480 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15490 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
154a0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
154b0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
154c0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
154d0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
154e0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
154f0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
15500 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
15510 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15520 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15530 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
15540 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
15550 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15560 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
15570 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
15580 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
15590 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
155a0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
155b0 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
155c0 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
155d0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
155e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
155f0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
15600 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
15610 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
15620 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
15630 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
15640 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
15650 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
15660 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
15670 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
15680 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
15690 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
156a0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
156b0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
156c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
156d0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
156e0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
156f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
15700 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
15710 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
15720 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
15730 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
15740 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
15750 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
15760 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
15770 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
15780 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15790 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
157a0 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
157b0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
157c0 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
157d0 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
157e0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
157f0 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  H17382} However,
15800 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
15810 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
15820 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
15830 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
15840 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
15850 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
15860 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
15870 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
15880 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
15890 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
158a0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
158b0 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
158c0 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
158d0 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
158e0 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
158f0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
15900 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
15910 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
15920 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
15930 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
15940 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
15950 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
15960 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
15970 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
15980 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
15990 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
159a0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
159b0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
159c0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
159d0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
159e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
159f0 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
15a00 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
15a10 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
15a20 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
15a30 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
15a40 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
15a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
15a60 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
15a70 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
15a80 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
15a90 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
15aa0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
15ab0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
15ac0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
15ad0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
15ae0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
15af0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
15b00 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
15b10 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
15b20 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
15b30 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
15b40 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
15b50 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
15b60 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
15b70 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
15b80 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
15b90 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
15ba0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
15bb0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
15bc0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
15bd0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
15be0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
15bf0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
15c00 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68  .** {H17303}  Th
15c10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
15c20 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
15c30 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
15c40 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
15c50 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79           a newly
15c60 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f   checked-out blo
15c70 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ck of at least N
15c80 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
15c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
15ca0 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
15cb0 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75  gned, or it retu
15cc0 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69  rns NULL if it i
15cd0 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20  s unable.**     
15ce0 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c        to fulfill
15cf0 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a   the request..**
15d00 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68  .** {H17304}  Th
15d10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
15d20 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
15d30 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
15d40 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20  ointer if.**    
15d50 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73         N is less
15d60 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
15d70 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48  o zero..**.** {H
15d80 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c  17305}  The [sql
15d90 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e  ite3_free(P)] in
15da0 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73  terface releases
15db0 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73   memory previous
15dc0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
15dd0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
15de0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15df0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
15e00 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
15e10 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20        making it 
15e20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65  available for re
15e30 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  use..**.** {H173
15e40 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  06}  A call to [
15e50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c  sqlite3_free(NUL
15e60 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73  L)] is a harmles
15e70 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b  s no-op..**.** {
15e80 48 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20  H17310}  A call 
15e90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
15ea0 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75  loc(0,N)] is equ
15eb0 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
15ec0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
15ed0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
15ee0 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  c(N)]..**.** {H1
15ef0 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7312}  A call to
15f00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15f10 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76  c(P,0)] is equiv
15f20 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
15f30 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
15f40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
15f50 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35  ]..**.** {H17315
15f60 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  }  The SQLite co
15f70 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33  re uses [sqlite3
15f80 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
15f90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
15fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e  .**           an
15fb0 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  d [sqlite3_free(
15fc0 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  )] for all of it
15fd0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
15fe0 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
15ff0 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f       deallocatio
16000 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  n needs..**.** {
16010 48 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71  H17318}  The [sq
16020 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
16030 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
16040 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
16050 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
16060 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f      to a block o
16070 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65  f checked-out me
16080 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
16090 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
160a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
160b0 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
160c0 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20  gned, or a NULL 
160d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
160e0 48 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73  H17321}  When [s
160f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
16100 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
16110 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
16120 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
16130 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68         copies th
16140 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20  e first K bytes 
16150 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20  of content from 
16160 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79  P into the newly
16170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c  .**           al
16180 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77  located block, w
16190 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65  here K is the le
161a0 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68  sser of N and th
161b0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20  e size of.**    
161c0 20 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65         the buffe
161d0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  r P..**.** {H173
161e0 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  22}  When [sqlit
161f0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
16200 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e   returns a non-N
16210 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20  ULL pointer, it 
16220 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
16230 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20     releases the 
16240 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
16250 7b 48 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b  {H17323}  When [
16260 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16270 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55  P,N)] returns NU
16280 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50  LL, the buffer P
16290 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
162a0 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72   not modified or
162b0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
162c0 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
162d0 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68  .** {A17350}  Th
162e0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
162f0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
16300 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
16310 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
16320 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73  **           mus
16330 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
16340 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
16350 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
16360 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  a prior.**      
16370 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20       invocation 
16380 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
16390 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
163a0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
163b0 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  t have.**       
163c0 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e      not yet been
163d0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
163e0 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20 61   {A17351}  The a
163f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
16400 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
16410 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
16420 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f             a blo
16430 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
16440 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
16450 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
16460 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
16470 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
16480 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16490 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
164a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
164b0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
164c0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
164d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
164e0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
164f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16500 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
16510 20 53 74 61 74 69 73 74 69 63 73 20 7b 48 31 37   Statistics {H17
16520 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a  370} <S30210>.**
16530 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
16540 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
16550 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
16560 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
16570 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
16580 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16590 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
165a0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
165b0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
165c0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
165d0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
165e0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
165f0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
16600 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
16610 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20  .**.** {H17371} 
16620 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
16630 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
16640 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
16650 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
16660 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d  **          of m
16670 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
16680 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
16690 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
166a0 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  eed)..**.** {H17
166b0 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  373} The [sqlite
166c0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
166d0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
166e0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
166f0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  m.**          va
16700 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
16710 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
16720 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
16730 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
16740 20 20 20 20 20 77 61 73 20 6c 61 73 74 20 72 65       was last re
16750 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  set..**.** {H173
16760 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72  74} The values r
16770 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
16780 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
16790 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
167a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
167b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
167c0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
167d0 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  head.**         
167e0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
167f0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
16800 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
16810 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
16820 20 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f            but no
16830 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
16840 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
16850 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
16860 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  brary.**        
16870 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20    routines that 
16880 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16890 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
168a0 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20  ** {H17375} The 
168b0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
168c0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
168d0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
168e0 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  alue of.**      
168f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
16900 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
16910 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
16920 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
16930 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
16940 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
16950 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54  r()] is true.  T
16960 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16970 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
16980 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16990 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
169a0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
169b0 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20   mark.**        
169c0 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72    prior to the r
169d0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
169e0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
169f0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
16a00 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
16a10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16a20 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
16a30 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
16a40 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
16a50 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
16a60 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30  enerator {H17390
16a70 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
16a80 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
16a90 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
16aa0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
16ab0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
16ac0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
16ad0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52   select random R
16ae0 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72  OWIDs when inser
16af0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
16b00 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
16b10 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
16b20 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
16b30 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20  ossible ROWID.  
16b40 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
16b50 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
16b60 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
16b70 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
16b80 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
16b90 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
16ba0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
16bb0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
16bc0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
16bd0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
16be0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  oses..**.** A ca
16bf0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
16c00 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
16c10 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
16c20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
16c30 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74  *.** The first t
16c40 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
16c50 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
16c60 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
16c70 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
16c80 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
16c90 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
16ca0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
16cb0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
16cc0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
16cd0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
16ce0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
16cf0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20  ] object..** On 
16d00 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
16d10 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
16d20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
16d30 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
16d40 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
16d50 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
16d60 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
16d70 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
16d80 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a  ss.** method..**
16d90 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
16da0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54  **.** {H17392} T
16db0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64  he [sqlite3_rand
16dc0 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74  omness(N,P)] int
16dd0 65 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20  erface writes N 
16de0 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20  bytes of.**     
16df0 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74       high-qualit
16e00 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  y pseudo-randomn
16e10 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
16e20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  P..*/.void sqlit
16e30 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
16e40 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
16e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16e60 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
16e70 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
16e80 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53  acks {H12500} <S
16e90 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70100>.**.** Thi
16ea0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
16eb0 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
16ec0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
16ed0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
16ee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16ef0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
16f00 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16f10 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
16f20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16f30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
16f40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
16f50 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
16f60 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
16f70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
16f80 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
16f90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16fa0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
16fb0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
16fc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16fd0 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
16fe0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
16ff0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
17000 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
17010 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
17020 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
17030 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
17040 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
17050 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17060 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
17070 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
17080 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
17090 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
170a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
170b0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
170c0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
170d0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
170e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
170f0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
17100 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
17110 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
17120 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
17130 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
17140 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
17150 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
17160 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
17170 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17180 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
17190 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
171a0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
171b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
171c0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
171d0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
171e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
171f0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
17200 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
17210 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
17220 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
17230 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
17240 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
17250 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
17260 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
17270 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
17280 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
17290 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
172a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
172b0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
172c0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
172d0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57  uested is ok.  W
172e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
172f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17300 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
17310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17320 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
17330 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
17340 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
17350 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
17360 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
17370 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
17380 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
17390 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20  ess is denied.  
173a0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
173b0 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  r code is [SQLIT
173c0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
173d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
173e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
173f0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
17400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
17410 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
17420 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
17430 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
17440 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
17450 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
17460 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
17470 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
17480 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
17490 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
174a0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
174b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
174c0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
174d0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
174e0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
174f0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
17500 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
17510 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  a table..**.** T
17520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
17530 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
17540 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17550 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
17560 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
17570 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
17580 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17590 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65  ) interface. The
175a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
175b0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
175c0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
175d0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
175e0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
175f0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
17600 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
17610 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
17620 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69  horized. The thi
17630 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
17640 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
17650 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
17660 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
17670 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
17680 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
17690 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
176a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
176b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
176c0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
176d0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
176e0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
176f0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
17700 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
17710 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
17720 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
17730 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
17740 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17750 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
17760 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
17770 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
17780 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
17790 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
177a0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
177b0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
177c0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
177d0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
177e0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
177f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
17800 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
17810 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
17820 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
17830 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
17840 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
17850 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
17860 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
17870 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
17880 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
17890 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
178a0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
178b0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
178c0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
178d0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
178e0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
178f0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
17900 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
17910 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
17920 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
17930 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
17940 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
17950 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
17960 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
17970 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
17980 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
17990 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
179a0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
179b0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
179c0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
179d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
179e0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
179f0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
17a00 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
17a10 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
17a20 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
17a30 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
17a40 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
17a50 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
17a60 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
17a70 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
17a80 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
17a90 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
17aa0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
17ab0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
17ac0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
17ad0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
17ae0 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73  vious call.  Dis
17af0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
17b00 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
17b10 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
17b20 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
17b30 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
17b40 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
17b50 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** When [sqlite3
17b60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
17b70 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
17b80 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
17b90 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
17ba0 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61  might be reprepa
17bb0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
17bc0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
17bd0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
17be0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
17bf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
17c00 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
17c10 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
17c20 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
17c30 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
17c40 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
17c50 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
17c60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  )]..**.** Note t
17c70 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
17c80 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
17c90 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
17ca0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
17cb0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
17cc0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
17cd0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
17ce0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
17cf0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
17d00 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
17d10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
17d20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17d30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20  .**.** {H12501} 
17d40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
17d50 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
17d60 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
17d70 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
17d80 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
17d90 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
17da0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17db0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  on D..**.** {H12
17dc0 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
17dd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17de0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
17df0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
17e00 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
17e10 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70  parseed and comp
17e20 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  iled..**.** {H12
17e30 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68  503} If the auth
17e40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17e50 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75  returns any valu
17e60 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
17e70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
17e80 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
17e90 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
17ea0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a  E_DENY], then.**
17eb0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 70            the ap
17ec0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66  plication interf
17ed0 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ace call that ca
17ee0 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
17ef0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17f00 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
17f10 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
17f20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
17f30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
17f40 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
17f50 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
17f60 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
17f70 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {H12504} When t
17f80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17f90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
17fa0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
17fb0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
17fc0 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
17fd0 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72  is processed nor
17fe0 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mally..**.** {H1
17ff0 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61  2505} When the a
18000 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18010 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18020 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
18030 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69 63            applic
18040 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20  ation interface 
18050 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
18060 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
18070 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18080 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
18090 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
180a0 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
180b0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
180c0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
180d0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
180e0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
180f0 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
18100 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  denied..**.** {H
18110 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
18120 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
18130 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
18140 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
18150 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
18160 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
18170 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
18180 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18190 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
181a0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
181b0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
181c0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
181d0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
181e0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
181f0 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
18200 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
18210 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
18220 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
18230 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
18240 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
18250 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
18260 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
18270 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20  .** {H12507} If 
18280 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18290 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
182a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
182b0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
182c0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
182d0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
182e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
182f0 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
18300 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
18310 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
18320 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
18330 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
18340 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DENY]..**.** {H
18350 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
18360 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18370 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18380 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
18390 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
183a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
183b0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
183c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
183d0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
183e0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54  **.** {H12511} T
183f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18400 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
18410 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
18420 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
18430 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
18440 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
18450 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
18460 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
18470 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
18480 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
18490 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20  ** {H12512} The 
184a0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
184b0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
184c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
184d0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
184e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
184f0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
18500 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
18510 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
18520 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
18530 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
18540 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
18550 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
18560 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
18570 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
18580 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
18590 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
185a0 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
185b0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orizer..**.** {H
185c0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
185d0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
185e0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
185f0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
18600 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18610 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
18620 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
18630 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
18640 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
18650 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18660 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
18670 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
18680 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
18690 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
186a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
186b0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
186c0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
186d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
186e0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
186f0 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
18700 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
18710 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
18720 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
18730 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18740 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
18750 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
18760 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
18770 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
18780 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
18790 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
187a0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
187b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
187c0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
187d0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
187e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
187f0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18800 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
18810 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
18820 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
18830 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18840 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
18850 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
18860 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
18870 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
18880 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
18890 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
188a0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
188b0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
188c0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
188d0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
188e0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
188f0 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
18900 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
18910 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18920 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
18930 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
18940 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18950 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
18960 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
18970 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
18980 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
18990 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
189a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
189b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
189c0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
189d0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
189e0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
189f0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
18a00 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
18a10 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
18a20 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
18a30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18a40 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
18a50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
18a60 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
18a70 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
18a80 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
18a90 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
18aa0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
18ab0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
18ac0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
18ad0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
18ae0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
18af0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
18b00 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
18b10 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
18b20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
18b30 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
18b40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
18b50 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
18b60 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18b70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18b80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18b90 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18ba0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18bb0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
18bc0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
18bd0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18be0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18bf0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
18c00 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
18c10 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
18c20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
18c30 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
18c40 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
18c50 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
18c60 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
18c70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
18c80 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
18c90 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
18ca0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18cb0 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73  * {H12551} The s
18cc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18cd0 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  to an.**        
18ce0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
18cf0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
18d00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
18d10 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74   shall be an int
18d20 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
18d30 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
18d40 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
18d50 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
18d60 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  what action.**  
18d70 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67          is being
18d80 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
18d90 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20  ** {H12552} The 
18da0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
18db0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  meters to the.**
18dc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
18dd0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18de0 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  r | authorizatio
18df0 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20  n callback].**  
18e00 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
18e10 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
18e20 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
18e30 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
18e40 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
18e50 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
18e60 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68  e] is used as th
18e70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18e80 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  er..**.** {H1255
18e90 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  3} The 5th param
18ea0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
18eb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18ec0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18ed0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18ee0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
18ef0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
18f00 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61       of the data
18f10 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22  base (example: "
18f20 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65  main", "temp", e
18f30 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
18f40 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  le..**.** {H1255
18f50 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  4} The 6th param
18f60 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
18f70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18f80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18f90 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18fa0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
18fb0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
18fc0 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
18fd0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
18fe0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
18ff0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
19000 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
19010 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
19020 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
19030 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
19040 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
19050 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
19060 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
19070 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
19080 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19090 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
190a0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
190b0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
190c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
190d0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
190e0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
190f0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
19100 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19120 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
19130 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
19140 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19150 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19170 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
19180 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
19190 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
191a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
191b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
191c0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
191d0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
191e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
191f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19200 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19210 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
19220 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
19230 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19240 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19250 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19260 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
19270 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
19280 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19290 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
192a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
192b0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
192c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
192d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
192e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
192f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
19300 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
19310 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
19320 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19340 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
19350 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
19360 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19370 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19390 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
193a0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
193b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
193c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
193d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
193e0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
193f0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
19400 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19410 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19430 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
19440 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
19450 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19460 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19480 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
19490 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
194a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
194b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
194c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194d0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
194e0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
194f0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
19500 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19520 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
19530 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
19540 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
19550 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19570 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
19580 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
19590 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
195a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
195b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
195c0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
195d0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
195e0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
195f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
19610 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
19620 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
19630 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19640 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
19660 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
19670 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
19680 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
19690 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
196a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
196b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
196c0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
196d0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
196e0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
196f0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
19700 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
19710 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
19720 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
19730 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19740 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
19750 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
19760 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
19770 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19780 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19790 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
197a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
197b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
197c0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
197d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
197e0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
197f0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
19800 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
19810 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19830 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
19840 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
19850 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
19860 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
19870 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19880 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
19890 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
198a0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
198b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
198c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
198d0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
198e0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
198f0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19900 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19910 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19920 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
19930 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
19940 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19950 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19960 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19970 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
19980 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
19990 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
199a0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
199b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199c0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
199d0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
199e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
199f0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19a10 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
19a20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75        31   /* Fu
19a30 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55  nction Name   NU
19a40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a60 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
19a70 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
19a80 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
19a90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19aa0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
19ab0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
19ac0 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
19ad0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
19ae0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  L.**.** These ro
19af0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
19b00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19b10 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
19b20 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
19b30 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
19b40 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
19b50 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
19b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
19b70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
19b80 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19b90 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
19ba0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
19bb0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
19bc0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19bd0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
19be0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19bf0 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
19c00 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
19c10 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
19c20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19c30 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
19c40 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
19c50 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
19c60 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
19c70 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
19c80 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19c90 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
19ca0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
19cb0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
19cc0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
19cd0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
19ce0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
19cf0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19d00 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
19d10 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19d20 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
19d30 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
19d40 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
19d50 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
19d60 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
19d70 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
19d80 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
19d90 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
19da0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
19db0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
19dc0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
19dd0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
19de0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
19df0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49   to run..**.** I
19e00 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
19e10 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61   {H12281} The ca
19e20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19e30 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
19e40 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
19e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
19e60 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
19e70 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
19e80 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  er an SQL statem
19e90 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
19ea0 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a   to execute and.
19eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
19ec0 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73  ever a trigger s
19ed0 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20  ubprogram first 
19ee0 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a  begins to run..*
19ef0 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61  *.** {H12282} Ea
19f00 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
19f10 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61  te3_trace()] sha
19f20 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  ll override the 
19f30 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
19f40 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
19f50 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
19f60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d  ..**.** {H12283}
19f70 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
19f80 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73  llback shall dis
19f90 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a  able tracing..**
19fa0 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65  .** {H12284} The
19fb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19fc0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
19fd0 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61  lback shall be a
19fe0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
19ff0 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72       the pointer
1a000 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33   which was the 3
1a010 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  rd argument to [
1a020 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
1a030 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d  ..**.** {H12285}
1a040 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1a050 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1a060 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1a070 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1a080 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a090 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
1a0a0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1a0b0 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   text.**        
1a0c0 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61    of the SQL sta
1a0d0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1a0e0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71   passed into [sq
1a0f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a100 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1a110 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
1a120 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  t, or an SQL com
1a130 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20  ment indicating 
1a140 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  the beginning.**
1a150 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74            of a t
1a160 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
1a170 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37  m..**.** {H12287
1a180 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
1a190 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1a1a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1a1b0 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76  rofile()] is inv
1a1c0 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
1a1d0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1a1e0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1a1f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20  .**.** {H12288} 
1a200 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1a210 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
1a220 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
1a230 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1a240 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72       the 3rd par
1a250 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1a260 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a  e3_profile()]..*
1a270 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68  *.** {H12289} Th
1a280 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1a290 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
1a2a0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1a2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1a2c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a2d0 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f  8 string that co
1a2e0 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c  ntains the compl
1a2f0 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20  ete text of.**  
1a300 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20          the SQL 
1a310 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20  statement as it 
1a320 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79  was processed by
1a330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a340 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
1a350 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
1a360 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alent..**.** {H1
1a370 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20  2290} The third 
1a380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a390 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1a3a0 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  k is an estimate
1a3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1a3c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
1a3d0 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c  noseconds of wal
1a3e0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71  l-clock time req
1a3f0 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  uired to.**     
1a400 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c       run the SQL
1a410 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20   statement from 
1a420 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e  start to finish.
1a430 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
1a440 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1a450 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1a460 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1a470 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1a480 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1a490 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1a4a0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1a4b0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1a4c0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1a4d0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1a4e0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1a4f0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1a500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a510 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1a520 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  s Callbacks {H12
1a530 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  910} <S60400>.**
1a540 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1a550 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
1a560 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1a570 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
1a580 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
1a590 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
1a5a0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1a5b0 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
1a5c0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1a5d0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1a5e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1a5f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1a600 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
1a610 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1a620 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1a630 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1a640 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1a650 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1a660 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f  **.** If the pro
1a670 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1a680 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1a690 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1a6a0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1a6b0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1a6c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1a6d0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1a6e0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1a6f0 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f   a GUI dialog bo
1a700 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  x..**.** INVARIA
1a710 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  NTS:.**.** {H129
1a720 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  11} The callback
1a730 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1a740 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1a750 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1a760 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ().**          i
1a770 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
1a780 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1a790 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1a7a0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1a7b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a7c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d  ..**.** {H12912}
1a7d0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
1a7e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1a7f0 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79  d once for every
1a800 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20   N virtual.**   
1a810 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f         machine o
1a820 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20  pcodes, where N 
1a830 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
1a840 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
1a850 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
1a860 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a870 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  ler()] call that
1a880 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
1a890 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c          the call
1a8a0 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c  back.  If N is l
1a8b0 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69  ess than 1, sqli
1a8c0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a8d0 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20  dler().**       
1a8e0 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20     acts as if a 
1a8f0 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61  NULL progress ha
1a900 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73  ndler had been s
1a910 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  pecified..**.** 
1a920 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {H12913} The pro
1a930 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
1a940 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
1a950 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
1a960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
1a970 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1a980 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1a990 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  r()..**.** {H129
1a9a0 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61  14} The fourth a
1a9b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1a9c0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a9d0 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20  ler() is a.**   
1a9e0 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e         void poin
1a9f0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
1aa00 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1aa10 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
1aa20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69  function each ti
1aa30 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  me it is invoked
1aa40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d  ..**.** {H12915}
1aa50 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
1aa60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
1aa70 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20  esults in fewer 
1aa80 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a  than N opcodes.*
1aa90 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67  *          being
1aaa0 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20   executed, then 
1aab0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1aac0 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69  lback is never i
1aad0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1aae0 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c  12916} Every cal
1aaf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
1ab00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1ab10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  ].**          ov
1ab20 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65  erwrites any pre
1ab30 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
1ab40 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ed progress hand
1ab50 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ler..**.** {H129
1ab60 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  17} If the progr
1ab70 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
1ab80 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65  back is NULL the
1ab90 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a  n no progress.**
1aba0 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65            handle
1abb0 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  r is invoked..**
1abc0 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20  .** {H12918} If 
1abd0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1abe0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
1abf0 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61  result other tha
1ac00 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  n 0, then.**    
1ac10 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69        the behavi
1ac20 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69  or is a if [sqli
1ac30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
1ac40 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64   had been called
1ac50 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53  ..**          <S
1ac60 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73  30500>.*/.void s
1ac70 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1ac80 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1ac90 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1aca0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1acb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1acc0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1acd0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1ace0 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30   {H12700} <S4020
1acf0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
1ad00 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1ad10 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1ad20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
1ad30 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
1ad40 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1ad50 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61  ment. The filena
1ad60 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1ad70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1ad80 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1ad90 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1ada0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1adb0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1adc0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1add0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1ade0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1adf0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1ae00 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1ae10 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1ae20 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1ae30 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1ae40 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1ae50 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1ae60 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1ae70 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1ae80 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1ae90 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1aea0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1aeb0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1aec0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1aed0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1aee0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1aef0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1af00 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61  t. If the databa
1af10 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1af20 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1af30 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1af40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1af50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1af60 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1af70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1af80 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ned.  The.** [sq
1af90 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1afa0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1afb0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
1afc0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1afd0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
1afe0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
1aff0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
1b000 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
1b010 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1b020 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1b030 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1b040 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1b050 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1b060 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1b070 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1b080 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1b090 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1b0a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1b0b0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1b0c0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1b0d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1b0e0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1b0f0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1b100 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1b110 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1b120 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1b130 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1b140 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1b150 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1b160 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1b170 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1b180 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1b190 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1b1a0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1b1b0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1b1c0 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1b1d0 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1b1e0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1b1f0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1b200 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1b210 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1b220 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1b230 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
1b240 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
1b250 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1b260 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1b270 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1b280 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1b290 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1b2a0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b2b0 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
1b2c0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1b2d0 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ags:.**.** <dl>.
1b2e0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
1b2f0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1b300 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1b310 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1b320 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1b330 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1b340 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1b350 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1b360 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1b370 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
1b380 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
1b390 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1b3a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1b3b0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1b3c0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1b3d0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1b3e0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1b3f0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1b400 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1b410 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1b420 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1b430 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1b440 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1b450 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1b460 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1b470 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1b480 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
1b490 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1b4a0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1b4b0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1b4c0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1b4d0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1b4e0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1b4f0 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1b500 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
1b510 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
1b520 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
1b530 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
1b540 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
1b550 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
1b560 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1b570 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1b580 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  16().</dd>.** </
1b590 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1b5a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1b5b0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1b5c0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1b5d0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1b5e0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1b5f0 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
1b600 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1b610 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
1b620 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
1b630 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1b640 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  EX] or [SQLITE_O
1b650 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1b660 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  lags,.** then th
1b670 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
1b680 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
1b690 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1b6a0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1b6b0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1b6c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b6d0 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1b6e0 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1b6f0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1b700 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1b710 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1b720 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1b730 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1b740 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1b750 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65  rt-time.  If the
1b760 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1b770 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1b780 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1b790 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b7a0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1b7b0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1b7c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1b7d0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1b7e0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1b7f0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1b800 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1b810 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1b820 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1b830 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1b840 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1b850 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1b860 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1b870 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1b880 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1b890 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
1b8a0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1b8b0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1b8c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b8d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1b8e0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1b8f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1b900 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1b910 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1b920 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1b930 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1b940 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1b950 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1b960 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1b970 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1b980 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1b990 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1b9a0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1b9b0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1b9c0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1b9d0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1b9e0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1b9f0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1ba00 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
1ba10 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1ba20 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1ba30 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1ba40 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1ba50 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1ba60 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1ba70 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1ba80 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1ba90 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1baa0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1bab0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1bac0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1bad0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
1bae0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1baf0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1bb00 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1bb10 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1bb20 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1bb30 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1bb40 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1bb50 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1bb60 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1bb70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1bb80 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
1bb90 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1bba0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1bbb0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1bbc0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1bbd0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1bbe0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1bbf0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1bc00 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1bc10 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1bc20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1bc30 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1bc40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1bc50 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1bc60 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1bc70 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1bc80 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1bc90 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1bca0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1bcb0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1bcc0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1bcd0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1bce0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1bcf0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1bd00 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1bd10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1bd20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bd30 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1bd40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  NTS:.**.** {H127
1bd50 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1bd60 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1bd70 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1bd80 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1bd90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1bda0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
1bdb0 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
1bdc0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1bdd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
1bde0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
1bdf0 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
1be00 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
1be10 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
1be20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1be30 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {H12702} The fil
1be40 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1be50 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1be60 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
1be70 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
1be80 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
1be90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1bea0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
1beb0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
1bec0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1bed0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
1bee0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1bef0 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63   {H12703} A succ
1bf00 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1bf10 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
1bf20 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1bf30 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1bf40 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1bf50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
1bf60 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
1bf70 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1bf80 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1bf90 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
1bfa0 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ppDb..**.** {H12
1bfb0 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
1bfc0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1bfd0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1bfe0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1bff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c000 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
1c010 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1c020 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1c030 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1c040 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1c050 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1c060 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lure..**.** {H12
1c070 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1c080 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1c090 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1c0a0 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1c0b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1c0c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1c0d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c0e0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1c0f0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37  8..**.** {H12707
1c100 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1c110 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1c120 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1c130 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1c140 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c150 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1c160 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1c170 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b  * {H12709} The [
1c180 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1c190 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1c1a0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1c1b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c1c0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1c1d0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1c1e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1c1f0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1c200 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c210 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1c220 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  REATE]..**.** {H
1c230 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1c240 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1c250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1c260 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1c270 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1c280 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1c290 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1c2a0 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1c2b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1c2c0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1c2d0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1c2e0 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68  * {H12712} If th
1c2f0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1c300 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c310 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1c320 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1c330 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1c340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c350 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1c360 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c370 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1c380 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1c390 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1c3a0 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1c3b0 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1c3c0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1c3d0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1c3e0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1c3f0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  system..**.** {H
1c400 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1c410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1c420 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1c430 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1c440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1c450 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1c460 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1c470 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1c480 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1c490 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1c4a0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1c4b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1c4c0 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65   {H12714} If the
1c4d0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1c4e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c4f0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1c500 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1c510 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1c520 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1c530 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1c540 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1c550 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1c560 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1c570 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1c580 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1c590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1c5a0 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1c5b0 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  base..**.** {H12
1c5c0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1c5d0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1c5e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1c5f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1c600 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1c610 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1c620 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1c630 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1c640 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1c650 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1c660 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1c670 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1c680 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1c690 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1c6a0 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1c6b0 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1c6c0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c6d0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1c6e0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1c6f0 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1c700 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39  o>.**.** {H12719
1c710 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1c720 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1c730 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1c740 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1c750 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1c760 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1c770 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1c780 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1c790 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1c7a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1c7b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1c7c0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1c7d0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1c7e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1c7f0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  todo>.**.** {H12
1c800 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1c810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1c820 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1c830 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1c840 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1c850 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1c860 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c870 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1c880 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1c890 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1c8a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1c8b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1c8c0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1c8d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1c8e0 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {H12723} Two [da
1c8f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c900 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1c910 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1c920 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1c930 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1c940 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1c950 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1c960 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1c970 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1c980 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1c990 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1c9a0 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1c9b0 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1c9c0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1c9d0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1c9e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1c9f0 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1ca00 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1ca10 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1ca20 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1ca30 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ca40 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ca50 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ca60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ca70 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1ca80 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ca90 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1caa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1cab0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1cac0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1cad0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1cae0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1caf0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1cb00 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1cb10 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1cb20 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1cb30 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1cb40 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1cb50 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1cb60 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1cb70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1cb80 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1cb90 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1cba0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1cbb0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1cbc0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1cbd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1cbe0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1cbf0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1cc00 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1cc10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1cc20 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1cc30 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20  ssages {H12800} 
1cc40 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60200>.**.** T
1cc50 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
1cc60 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
1cc70 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1cc80 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
1cc90 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1cca0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1ccb0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1ccc0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
1ccd0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
1cce0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1ccf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1cd00 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
1cd10 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
1cd20 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
1cd30 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
1cd40 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
1cd50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1cd60 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
1cd70 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
1cd80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
1cd90 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1cda0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1cdb0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1cdc0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1cdd0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1cde0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1cdf0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1ce00 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1ce10 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
1ce20 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ce30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1ce40 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1ce50 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1ce60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1ce70 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1ce80 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1ce90 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1cea0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1ceb0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1cec0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1ced0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1cee0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1cef0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1cf00 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1cf10 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ce functions..**
1cf20 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1cf30 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1cf40 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1cf50 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1cf60 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1cf70 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1cf80 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1cf90 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1cfa0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1cfb0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1cfc0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1cfd0 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  t be set..**.** 
1cfe0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1cff0 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b  * {H12801} The [
1d000 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d010 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
1d020 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1d030 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72  c.**          [r
1d040 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
1d050 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1d060 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1d070 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20  st recently.**  
1d080 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69          failed i
1d090 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73  nterface call as
1d0a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1d0b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1d0c0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
1d0d0 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73   {H12803} The [s
1d0e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29  qlite3_errmsg(D)
1d0f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1d100 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20  rrmsg16(D)].**  
1d110 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
1d120 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  es return Englis
1d130 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20  h-language text 
1d140 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a  that describes.*
1d150 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65  *          the e
1d160 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74  rror in the most
1d170 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c  ly recently fail
1d180 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1d190 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  l,.**          e
1d1a0 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72  ncoded as either
1d1b0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1d1c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1d1d0 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68  *.** {H12807} Th
1d1e0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1d1f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
1d200 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71  rrmsg()] and [sq
1d210 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1d220 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
1d230 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
1d240 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e  e next SQLite in
1d250 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a  terface call..**
1d260 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c  .** {H12808} Cal
1d270 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
1d280 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
1d290 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63  eturn an error c
1d2a0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
1d2b0 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
1d2c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
1d2d0 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  ) do not.**     
1d2e0 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20       change the 
1d2f0 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65  error code or me
1d300 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62  ssage returned b
1d310 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1d320 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1d330 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1d340 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1d350 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1d360 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49  **.** {H12809} I
1d370 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
1d380 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65  re not associate
1d390 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  d with a specifi
1d3a0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  c.**          [d
1d3b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d3c0 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  on] (examples:.*
1d3d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1d3e0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f  te3_mprintf()] o
1d3f0 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  r [sqlite3_enabl
1d400 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1d410 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f  ].**          do
1d420 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1d430 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1d440 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1d450 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d460 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
1d470 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
1d480 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
1d490 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d4a0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1d4b0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1d4c0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1d4d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1d4e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1d4f0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1d500 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d510 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1d520 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1d530 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1d540 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1d550 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1d560 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d570 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1d580 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1d590 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1d5a0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1d5b0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1d5c0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1d5d0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1d5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d5f0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1d600 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1d610 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1d620 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1d630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1d640 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1d650 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1d660 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1d670 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1d680 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1d690 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1d6a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d6b0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1d6c0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1d6d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1d6e0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1d6f0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1d700 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1d710 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1d720 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1d730 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1d740 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1d750 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1d760 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1d770 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1d780 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1d790 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1d7a0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1d7b0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1d7c0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1d7d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1d7e0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1d7f0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1d800 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1d810 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1d820 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1d830 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1d840 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1d850 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1d860 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1d870 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1d880 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1d890 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1d8a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d8b0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1d8c0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1d8d0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1d8e0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1d8f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1d900 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1d910 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1d920 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1d930 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1d940 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1d950 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1d960 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1d970 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1d980 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1d990 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1d9a0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1d9b0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1d9c0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1d9d0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1d9e0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1d9f0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1da00 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1da10 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1da20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1da30 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1da40 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1da50 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1da60 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1da70 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1da80 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1da90 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1daa0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1dab0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1dac0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1dad0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1dae0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1daf0 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a   a hard upper.**
1db00 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20   bound set by a 
1db10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70  compile-time C p
1db20 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1db30 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d  o named SQLITE_M
1db40 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20  AX_XYZ..** (The 
1db50 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1db60 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1db70 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
1db80 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
1db90 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1dba0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1dbb0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1dbc0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1dbd0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1dbe0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
1dbf0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
1dc00 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1dc10 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1dc20 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1dc30 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1dc40 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1dc50 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1dc60 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1dc70 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1dc80 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1dc90 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1dca0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1dcb0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1dcc0 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72   a.** webbrowser
1dcd0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
1dce0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
1dcf0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
1dd00 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
1dd10 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
1dd20 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
1dd30 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
1dd40 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
1dd50 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
1dd60 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
1dd70 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
1dd80 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
1dd90 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
1dda0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
1ddb0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
1ddc0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
1ddd0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
1dde0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
1ddf0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
1de00 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
1de10 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
1de20 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
1de30 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
1de40 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1de50 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1de60 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
1de70 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
1de80 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
1de90 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
1dea0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1deb0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
1dec0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
1ded0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
1dee0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
1def0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1df00 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
1df10 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
1df20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
1df30 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
1df40 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
1df50 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1df60 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73  .** {H12762} A s
1df70 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1df80 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1df90 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1dfa0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
1dfb0 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73  positive changes
1dfc0 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
1dfd0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
1dfe0 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
1dff0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1e000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1e010 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f   to the lesser o
1e020 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
1e030 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20   upper.**       
1e040 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20     bound on the 
1e050 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69  size of C that i
1e060 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
1e070 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  -time..**.** {H1
1e080 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
1e090 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1e0a0 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1e0b0 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
1e0c0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
1e0d0 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
1e0e0 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  te of the [datab
1e0f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e100 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  D unchanged..**.
1e110 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75  ** {H12769} A su
1e120 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1e130 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1e140 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20  D,C,V)] returns 
1e150 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e160 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
1e170 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1e180 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1e190 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e1a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1e1b0 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77  ction] D as it w
1e1c0 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  as prior to the 
1e1d0 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  call..*/.int sql
1e1e0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1e1f0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1e200 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1e210 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1e220 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1e230 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48  ries {H12790} <H
1e240 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  12760>.** KEYWOR
1e250 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
1e260 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65  ory} {limit cate
1e270 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
1e280 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
1e290 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70  fine various asp
1e2a0 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62  ects of a [datab
1e2b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
1e2c0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
1e2d0 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62  imited in size b
1e2e0 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  y calls to [sqli
1e2f0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1e300 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   The meanings of
1e310 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1e320 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  its are as follo
1e330 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ws:.**.** <dl>.*
1e340 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e350 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1e360 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e370 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1e380 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1e390 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
1e3a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e3b0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1e3c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e3d0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1e3e0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
1e3f0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1e400 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e410 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1e420 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e430 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1e440 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1e450 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1e460 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1e470 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74  of a SELECT or t
1e480 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e490 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1e4a0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
1e4b0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
1e4c0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
1e4d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1e4e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1e4f0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1e500 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e510 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1e520 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1e530 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1e540 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e550 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1e560 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1e570 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e580 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1e590 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1e5a0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1e5b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e5c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1e5d0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1e5e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e5f0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1e600 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1e610 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1e620 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1e630 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1e640 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1e650 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e660 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
1e670 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e680 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e690 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
1e6a0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
1e6b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e6c0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1e6d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e6e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e6f0 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  f attached datab
1e700 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ases.</dd>.**.**
1e710 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e720 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1e730 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e740 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1e750 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1e760 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1e770 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47  the LIKE or.** G
1e780 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  LOB operators.</
1e790 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1e7a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1e7b0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1e7c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e7d0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1e7e0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1e7f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1e800 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1e810 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1e820 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e830 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
1e840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e850 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
1e860 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1e870 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1e880 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1e890 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
1e8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e8b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1e8c0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1e8d0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1e8e0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1e8f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1e900 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
1e910 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1e920 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1e930 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
1e940 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
1e950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1e960 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
1e970 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
1e980 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
1e990 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
1e9a0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
1e9b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1e9c0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1e9d0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
1e9e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e9f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1ea00 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
1ea10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1ea20 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
1ea30 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
1ea40 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
1ea50 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1ea60 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1ea70 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1ea80 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1ea90 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1eaa0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1eab0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1eac0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1ead0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1eae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1eaf0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1eb00 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1eb10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1eb20 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1eb30 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73  prior call to [s
1eb40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1eb50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1eb60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1eb70 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1eb80 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1eb90 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
1eba0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
1ebb0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
1ebc0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
1ebd0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1ebe0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
1ebf0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
1ec00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ec10 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
1ec20 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
1ec30 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1ec40 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
1ec50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ec60 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
1ec70 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
1ec80 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1ec90 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1eca0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1ecb0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
1ecc0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1ecd0 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73  tor. If nByte is
1ece0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1ecf0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1ed00 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
1ed10 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
1ed20 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
1ed30 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1ed40 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
1ed50 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
1ed60 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
1ed70 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
1ed80 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
1ed90 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
1eda0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
1edb0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
1edc0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
1edd0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
1ede0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
1edf0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
1ee00 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
1ee10 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1ee20 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1ee30 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
1ee40 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1ee50 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1ee60 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
1ee70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1ee80 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
1ee90 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
1eea0 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
1eeb0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1eec0 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a  bytes..**.** *pz
1eed0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1eee0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1eef0 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
1ef00 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66   end of the.** f
1ef10 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1ef20 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1ef30 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1ef40 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
1ef50 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
1ef60 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1ef70 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1ef80 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
1ef90 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
1efa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
1efb0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
1efc0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
1efd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1efe0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
1eff0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
1f000 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1f010 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20  p()].  If there 
1f020 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1f030 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1f040 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20  o NULL.  If the 
1f050 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1f060 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1f070 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1f080 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1f090 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1f0a0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1f0b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31   to NULL..** {A1
1f0c0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
1f0d0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1f0e0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1f0f0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1f100 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1f110 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1f120 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1f130 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1f140 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1f150 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
1f160 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
1f170 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
1f180 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1f190 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1f1a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1f1b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f1c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1f1d0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1f1e0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1f1f0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1f200 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1f210 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1f220 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1f230 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1f240 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f250 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1f260 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1f270 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
1f280 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1f290 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1f2a0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1f2b0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1f2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1f2d0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1f2e0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1f2f0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1f300 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1f310 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1f320 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1f330 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
1f340 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
1f350 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1f360 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
1f370 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1f380 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1f390 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1f3a0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1f3b0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1f3c0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1f3d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1f3e0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1f3f0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1f400 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1f410 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1f420 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
1f430 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1f440 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1f450 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1f460 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1f470 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1f480 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1f490 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1f4a0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1f4b0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1f4c0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1f4d0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1f4e0 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1f4f0 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1f500 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1f510 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1f520 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1f530 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1f540 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1f550 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1f560 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1f570 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1f580 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1f590 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1f5a0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1f5b0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1f5c0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
1f5d0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1f5e0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1f5f0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1f600 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1f610 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1f620 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1f630 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1f640 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
1f650 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
1f660 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1f670 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
1f680 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
1f690 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
1f6a0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
1f6b0 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
1f6c0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
1f6d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1f6e0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
1f6f0 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
1f700 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
1f710 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
1f720 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
1f730 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
1f740 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
1f750 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
1f760 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
1f770 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1f780 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1f790 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
1f7a0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1f7b0 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {H13011} The [sq
1f7c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1f7d0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1f7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f7f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f800 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1f810 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1f820 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1f830 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1f840 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1f850 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
1f860 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {H13012} The [sq
1f870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1f880 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1f890 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1f8a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f8b0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
1f8c0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
1f8d0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
1f8e0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
1f8f0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
1f900 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
1f910 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1f920 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48   order..**.** {H
1f930 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
1f940 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
1f950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f960 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
1f970 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
1f980 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
1f990 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
1f9a0 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20  n zero, the SQL 
1f9b0 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  text is.**      
1f9c0 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53      read from zS
1f9d0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1f9e0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1f9f0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1fa00 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68  * {H13014} If th
1fa10 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1fa20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1fa30 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1fa40 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
1fa50 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
1fa60 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d  variants is non-
1fa70 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
1fa80 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79  t most nBytes by
1fa90 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
1faa0 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72     SQL text is r
1fab0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a  ead from zSql..*
1fac0 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e  *.** {H13015} In
1fad0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fae0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50  e_v2(db,zSql,N,P
1faf0 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74  ,pzTail)] and it
1fb00 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20  s variants.**   
1fb10 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53         if the zS
1fb20 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  ql input text co
1fb30 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e  ntains more than
1fb40 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65   one SQL stateme
1fb50 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  nt.**          a
1fb60 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  nd pzTail is not
1fb70 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54   NULL, then *pzT
1fb80 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1fb90 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20  oint to the.**  
1fba0 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79          first by
1fbb0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1fbc0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1fbd0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1fbe0 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ql..**          
1fbf0 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20  <todo>What does 
1fc00 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f  *pzTail point to
1fc10 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65   if there is one
1fc20 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64   statement?</tod
1fc30 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36  o>.**.** {H13016
1fc40 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1fc50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1fc60 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1fc70 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29  ql,N,ppStmt,...)
1fc80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
1fc90 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
1fca0 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f  ants writes into
1fcb0 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74   *ppStmt a point
1fcc0 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
1fcd0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1fce0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
1fcf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  a pointer to NUL
1fd00 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69  L if zSql contai
1fd10 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ns.**          n
1fd20 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  othing other tha
1fd30 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20  n whitespace or 
1fd40 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  comments..**.** 
1fd50 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {H13019} The [sq
1fd60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1fd70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
1fd80 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
1fd90 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1fda0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
1fdb0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
1fdc0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
1fdd0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1fde0 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {H13021} Before
1fdf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fe00 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
1fe10 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
1fe20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
1fe30 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
1fe40 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
1fe50 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1fe60 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c  an [SQLITE_OK]),
1fe70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1fe80 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53  y first set *ppS
1fe90 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  tmt to NULL..*/.
1fea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1feb0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
1fec0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1fed0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1fee0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1fef0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1ff00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1ff10 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1ff20 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1ff30 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1ff40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1ff50 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1ff60 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1ff70 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1ff80 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1ff90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1ffa0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1ffb0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1ffc0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1ffd0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1ffe0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1fff0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
20000 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
20010 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
20020 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
20030 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
20040 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
20050 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
20060 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
20070 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
20080 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
20090 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
200a0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
200b0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
200c0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
200d0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
200e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
200f0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
20100 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
20110 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
20120 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
20130 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
20140 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20150 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
20160 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
20170 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
20180 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
20190 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
201a0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
201b0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
201c0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
201d0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
201e0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
201f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
20200 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
20210 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
20220 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
20230 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
20240 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
20250 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
20260 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
20270 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
20280 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
20290 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
202a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
202b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
202c0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
202d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
202e0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
202f0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
20300 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
20310 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
20320 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
20330 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
20340 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
20350 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
20360 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
20370 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
20380 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
20390 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
203a0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
203b0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
203c0 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76 69  APIREF: Retrievi
203d0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
203e0 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30   {H13100} <H1300
203f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
20400 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
20410 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
20420 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
20430 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
20440 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
20450 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
20460 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
20470 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
20480 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
20490 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
204a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
204b0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
204c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
204d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
204e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  TS:.**.** {H1310
204f0 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
20500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
20510 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
20520 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
20530 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
20540 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
20550 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
20560 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20570 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
20580 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
20590 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74  epare16_v2()], t
205a0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
205b0 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ()] returns.**  
205c0 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
205d0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
205e0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f  inated string co
205f0 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38  ntaining a UTF-8
20600 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20   rendering.**   
20610 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72         of the or
20620 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65  iginal SQL state
20630 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ment..**.** {H13
20640 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65  102} If the [pre
20650 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20660 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
20670 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
20680 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20690 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
206a0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
206b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
206c0 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
206d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
206e0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
206f0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
20700 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
20710 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
20720 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
20730 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
20740 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69  qlite3_sql(S)] i
20750 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
20760 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
20770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20780 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20  t] S is deleted 
20790 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
207a0 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a  inalize(S)]..*/.
207b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
207c0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
207d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
207e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
207f0 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
20800 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48   Value Object {H
20810 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15000} <S20200>.
20820 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
20830 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20840 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
20850 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20860 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
20870 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
20880 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
20890 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
208a0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
208b0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
208c0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
208d0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
208e0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
208f0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
20900 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20   stores. Values 
20910 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
20920 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
20930 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
20940 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
20950 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
20960 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
20970 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
20980 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20990 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
209a0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
209b0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
209c0 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
209d0 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
209e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
209f0 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
20a00 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
20a10 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
20a20 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
20a30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20a40 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
20a50 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
20a60 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
20a70 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
20a80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
20a90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
20aa0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
20ab0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20ac0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
20ad0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
20ae0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
20af0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
20b00 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
20b10 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
20b20 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
20b30 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
20b40 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20b50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20b60 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
20b70 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
20b80 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20b90 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
20ba0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
20bb0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
20bc0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
20bd0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
20be0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
20bf0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
20c00 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
20c10 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
20c20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
20c30 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
20c40 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
20c50 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
20c60 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
20c70 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
20c80 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
20c90 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
20ca0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
20cb0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20cc0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
20cd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
20ce0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
20cf0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
20d00 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
20d10 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
20d20 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
20d30 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
20d40 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
20d50 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
20d60 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
20d70 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
20d80 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  een between prot
20d90 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
20da0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
20db0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
20dc0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
20dd0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
20de0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20df0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
20e00 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
20e10 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
20e20 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
20e30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
20e40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
20e50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
20e60 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
20e70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
20e80 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
20e90 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
20ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
20eb0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
20ec0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
20ed0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
20ee0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
20ef0 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
20f00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
20f10 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
20f20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20f30 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
20f40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
20f50 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
20f60 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
20f70 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
20f80 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
20f90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20fa0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
20fb0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
20fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
20fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20fe0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
20ff0 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36  text Object {H16
21000 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  001} <S20200>.**
21010 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
21020 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
21030 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
21040 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
21050 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
21060 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
21070 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
21080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
21090 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
210a0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
210b0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
210c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
210d0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
210e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
210f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
21100 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
21110 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
21120 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
21130 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
21140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
21150 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
21160 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
21170 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
21180 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
21190 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
211a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
211b0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
211c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
211d0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
211e0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
211f0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
21200 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
21210 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
21220 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
21230 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
21240 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
21250 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
21260 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35  Statements {H135
21270 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20  00} <S70300>.** 
21280 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
21290 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
212a0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
212b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
212c0 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
212d0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
212e0 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
212f0 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
21300 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ing}.**.** In th
21310 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
21320 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
21330 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21340 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
21350 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
21360 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
21370 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e   parameter in on
21380 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  e of these forms
21390 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
213a0 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
213b0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
213c0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
213d0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
213e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
213f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
21400 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
21410 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
21420 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
21430 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c  and VVV is an al
21440 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
21450 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20  meter name. The 
21460 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
21470 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
21480 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
21490 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
214a0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
214b0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
214c0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
214d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
214e0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
214f0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
21500 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
21510 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
21520 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
21530 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
21540 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
21550 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
21560 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
21570 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
21580 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21590 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
215a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
215b0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
215c0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
215d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
215e0 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74  set..** The left
215f0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
21600 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
21610 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
21620 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
21630 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
21640 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
21650 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
21660 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
21670 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
21680 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
21690 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
216a0 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64  ence..** The ind
216b0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
216c0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
216d0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
216e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
216f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21700 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
21710 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65  sired.  The inde
21720 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
21730 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
21740 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
21750 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
21760 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
21770 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
21780 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
21790 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
217a0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
217b0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
217c0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
217d0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
217e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
217f0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
21800 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
21810 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f  *.** In those ro
21820 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
21830 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
21840 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
21850 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
21860 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
21870 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
21880 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
21890 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
218a0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
218b0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
218c0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
218d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
218e0 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
218f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
21900 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
21910 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
21920 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
21930 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
21940 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
21950 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
21960 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   The fifth argum
21970 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
21980 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
21990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
219a0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
219b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
219c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
219d0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
219e0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
219f0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
21a00 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
21a10 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65   with it. If the
21a20 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
21a30 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
21a40 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
21a50 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
21a60 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
21a70 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
21a80 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
21a90 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
21aa0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
21ab0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
21ac0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74  ..** If the fift
21ad0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
21ae0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
21af0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
21b00 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
21b10 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
21b20 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
21b30 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
21b40 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
21b50 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21b60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
21b70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21b80 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
21b90 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
21ba0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
21bb0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
21bc0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
21bd0 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73  .  A zeroblob us
21be0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
21bf0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
21c00 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
21c10 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
21c20 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
21c30 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
21c40 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
21c50 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
21c60 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
21c70 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
21c80 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
21c90 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
21ca0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21cb0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
21cc0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
21cd0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41  ] routines..** A
21ce0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
21cf0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
21d00 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
21d10 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
21d20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21d30 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
21d40 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
21d50 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
21d60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21d70 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
21d80 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
21d90 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
21da0 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
21db0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
21dc0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
21dd0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
21de0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21df0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
21e00 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
21e10 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
21e20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
21e30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
21e40 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
21e50 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
21e60 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
21e70 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
21e80 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
21e90 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
21ea0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
21eb0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
21ec0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
21ed0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
21ee0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
21ef0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  loc() fails..** 
21f00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
21f10 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
21f20 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
21f30 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
21f40 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
21f50 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
21f60 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
21f70 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
21f80 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
21f90 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
21fa0 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
21fb0 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
21fc0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
21fd0 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
21fe0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
21ff0 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
22000 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
22010 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
22020 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
22030 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
22040 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
22050 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
22060 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
22070 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
22080 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
22090 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
220a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
220b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
220c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
220d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
220e0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
220f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22100 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
22110 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
22120 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68  *.** {H13506} Th
22130 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  e [SQL statement
22140 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67   compiler] recog
22150 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20  nizes tokens of 
22160 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20  the forms.**    
22170 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e        "?", "?NNN
22180 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56  ", "$VVV", ":VVV
22190 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73  ", and "@VVV" as
221a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c   SQL parameters,
221b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
221c0 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65  re NNN is any se
221d0 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
221e0 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20   more digits.** 
221f0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
22200 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65  re VVV is any se
22210 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
22220 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72   more alphanumer
22230 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ic.**          c
22240 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a  haracters or "::
22250 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  " optionally fol
22260 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e  lowed by a strin
22270 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  g containing.** 
22280 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63           no spac
22290 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64  es and contained
222a0 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65   within parenthe
222b0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ses..**.** {H135
222c0 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20  09} The initial 
222d0 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20  value of an SQL 
222e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
222f0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32  L..**.** {H13512
22300 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
22310 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65  n "?" SQL parame
22320 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65  ter is one large
22330 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20  r than the.**   
22340 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69         largest i
22350 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
22360 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66  meter to the lef
22370 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20  t, or 1 if.**   
22380 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69         the "?" i
22390 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53  s the leftmost S
223a0 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  QL parameter..**
223b0 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65  .** {H13515} The
223c0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e   index of an "?N
223d0 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  NN" SQL paramete
223e0 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72  r is the integer
223f0 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33   NNN..**.** {H13
22400 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  518} The index o
22410 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56  f an ":VVV", "$V
22420 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53  VV", or "@VVV" S
22430 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  QL parameter is.
22440 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22450 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65  same as the inde
22460 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63  x of leftmost oc
22470 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65  currences of the
22480 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
22490 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20    parameter, or 
224a0 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  one more than th
224b0 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
224c0 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  over all.**     
224d0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20       parameters 
224e0 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74  to the left if t
224f0 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74  his is the first
22500 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20   occurrence.**  
22510 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20          of this 
22520 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20  parameter, or 1 
22530 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c  if this is the l
22540 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65  eftmost paramete
22550 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31  r..**.** {H13521
22560 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
22570 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
22580 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51  ails with an [SQ
22590 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20  LITE_RANGE].**  
225a0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66          error if
225b0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
225c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
225d0 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a  s less than 1.**
225e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65            or gre
225f0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f  ater than the co
22600 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54  mpile-time SQLIT
22610 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
22620 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  UMBER.**        
22630 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
22640 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c  ** {H13524} Call
22650 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22660 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22670 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
22680 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
22690 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
226a0 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
226b0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
226c0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
226d0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
226e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
226f0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
22700 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c  ** {H13527} Call
22710 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
22720 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22730 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
22740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
22750 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
22760 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
22770 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
22780 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30  N..**.** {H13530
22790 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
227a0 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
227b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
227c0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
227d0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
227e0 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
227f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22800 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
22810 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61  * {H13533} In ca
22820 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
22830 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
22840 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
22850 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
22860 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
22870 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
22880 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22890 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
228a0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
228b0 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
228c0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
228d0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
228e0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
228f0 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
22900 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
22910 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
22920 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  H13536} In calls
22930 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22940 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
22950 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
22960 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22970 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
22980 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
22990 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
229a0 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
229b0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
229c0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
229d0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
229e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39  e..**.** {H13539
229f0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22a00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22a10 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
22a20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22a30 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
22a40 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
22a50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22a60 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
22a70 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
22a80 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
22a90 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
22aa0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
22ab0 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
22ac0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
22ad0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
22ae0 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
22af0 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
22b00 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
22b10 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
22b20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
22b30 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
22b40 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
22b50 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  H13542} In calls
22b60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22b70 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
22b80 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
22b90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22ba0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
22bb0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22bc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22bd0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
22be0 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
22bf0 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
22c00 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
22c10 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
22c20 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
22c30 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
22c40 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
22c50 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72  he value V befor
22c60 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
22c70 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20  .** {H13545} In 
22c80 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22c90 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
22ca0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
22cb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22cc0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22cd0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
22ce0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22cf0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22d00 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
22d10 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
22d20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
22d30 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
22d40 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
22d50 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
22d60 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
22d70 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73  e V after it has
22d80 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
22d90 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  the value V..**.
22da0 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63  ** {H13548} In c
22db0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22dc0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
22dd0 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
22de0 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
22df0 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f       is a BLOB o
22e00 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
22e10 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
22e20 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
22e30 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31  e..**.** {H13551
22e40 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22e50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
22e60 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
22e70 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
22e80 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
22e90 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
22ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
22eb0 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
22ec0 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
22ed0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22ee0 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
22ef0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22f00 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
22f10 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
22f20 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
22f30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
22f40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
22f50 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
22f60 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
22f70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
22f80 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
22f90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
22fa0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22fb0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
22fc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
22fd0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
22fe0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
22ff0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
23000 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
23010 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
23020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23030 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
23040 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
23050 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
23060 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
23070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23080 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
23090 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
230a0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
230b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
230c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
230d0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
230e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
230f0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
23100 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
23110 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
23120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
23130 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
23140 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d  ameters {H13600}
23150 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
23160 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
23170 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
23180 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
23190 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
231a0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
231b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
231c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
231d0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
231e0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
231f0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
23200 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
23210 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
23220 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
23230 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
23240 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
23250 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
23260 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
23270 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
23280 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
23290 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
232a0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
232b0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
232c0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
232d0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
232e0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
232f0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
23300 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
23310 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
23320 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
23330 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
23340 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
23350 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
23360 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
23370 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
23380 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
23390 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
233a0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
233b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
233c0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
233d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
233e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
233f0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
23400 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
23410 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73   {H13601} The [s
23420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23430 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20  meter_count(S)] 
23440 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23450 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
23460 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
23470 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  of all SQL param
23480 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  eters in the.** 
23490 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
234a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
234b0 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61   or 0 if S conta
234c0 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
234d0 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
234e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
234f0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
23500 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
23510 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
23520 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
23530 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53  eter {H13620} <S
23540 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70300>.**.** Thi
23550 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
23560 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
23570 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
23580 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61  -th.** [SQL para
23590 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65  meter] in a [pre
235a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
235b0 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
235c0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
235d0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
235e0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
235f0 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
23600 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
23610 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
23620 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
23630 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
23640 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
23650 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
23660 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
23670 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
23680 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
23690 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
236a0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
236b0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
236c0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
236d0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
236e0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
236f0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f  .** and are also
23700 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
23710 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
23720 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  eters"..**.** Th
23730 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
23740 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
23750 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
23760 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
23770 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
23780 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
23790 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
237a0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
237b0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
237c0 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
237d0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
237e0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
237f0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
23800 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
23810 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
23820 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
23830 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
23840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23850 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
23860 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23870 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
23880 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
23890 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
238a0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
238b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
238c0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
238d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
238e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
238f0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
23900 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
23910 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13621} The [sql
23920 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23930 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ter_name(S,N)] i
23940 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55  .**          a U
23960 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
23970 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  f the name of th
23980 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
23990 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  in.**          t
239a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
239b0 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67  tement] S having
239c0 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20   index N, or.** 
239d0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66           NULL if
239e0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c   there is no SQL
239f0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
23a00 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68  index N or if th
23a10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
23a20 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
23a30 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79  ex N is an anony
23a40 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22  mous parameter "
23a50 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ?"..*/.const cha
23a60 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
23a70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
23a80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23a90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23aa0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
23ab0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
23ac0 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
23ad0 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
23ae0 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
23af0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
23b00 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
23b10 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
23b20 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
23b30 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
23b40 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
23b50 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
23b60 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
23b70 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
23b80 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
23b90 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
23ba0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
23bb0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
23bc0 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
23bd0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
23be0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
23bf0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
23c00 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23c10 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
23c20 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
23c30 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
23c40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
23c50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
23c60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
23c70 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
23c80 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
23c90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23ca0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
23cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
23cc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
23cd0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
23ce0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23cf0 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  13641} The [sqli
23d00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23d10 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69  er_index(S,N)] i
23d20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
23d40 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
23d50 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b  rameter in the [
23d60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23d70 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
23d80 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74  S whose name mat
23d90 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73  ches the UTF-8 s
23da0 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66  tring N, or 0 if
23db0 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20   there is.**    
23dc0 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a        no match..
23dd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
23de0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23df0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
23e00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
23e10 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
23e20 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
23e30 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
23e40 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23e50 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30  nt {H13660} <S70
23e60 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  300>.**.** Contr
23e70 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
23e80 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
23e90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23ea0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
23eb0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
23ec0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
23ed0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
23ee0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23ef0 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
23f00 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
23f10 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
23f20 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
23f30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23f40 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b  * {H13661} The [
23f50 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23f60 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
23f70 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20  face resets all 
23f80 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
23f90 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
23fa0 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  gs in the [prepa
23fb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23fc0 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a   back to NULL..*
23fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
23fe0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
23ff0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
24000 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
24010 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
24020 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
24030 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30  {H13710} <S10700
24040 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
24050 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
24060 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
24070 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
24080 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
24090 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
240a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
240b0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
240c0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
240d0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
240e0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
240f0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
24100 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
24110 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24120 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65  .** {H13711} The
24130 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24140 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
24150 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24160 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
24170 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
24180 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
24190 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
241a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
241b0 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
241c0 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20        or 0 if S 
241d0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
241e0 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  e a result set..
241f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
24200 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
24210 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24220 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24230 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
24240 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
24250 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30  {H13720} <S10700
24260 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
24270 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
24280 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
24290 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
242a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
242b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
242c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
242d0 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
242e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
242f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
24300 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
24310 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
24320 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
24330 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
24340 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
24350 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
24360 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
24370 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
24380 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
24390 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
243a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
243b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
243c0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
243d0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
243e0 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ent. The second 
243f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
24400 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
24410 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  r.  The leftmost
24420 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
24430 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
24440 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
24450 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
24460 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
24470 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24480 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
24490 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
244a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
244b0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
244c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
244d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
244e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
244f0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
24500 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
24510 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
24520 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
24530 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
24540 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
24550 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
24560 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
24570 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
24580 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
24590 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
245a0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
245b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
245c0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
245d0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
245e0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
245f0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
24600 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
24610 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
24620 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
24630 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
24640 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
24650 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
24660 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
24670 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
24680 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
24690 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
246a0 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  e next..**.** IN
246b0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
246c0 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65  {H13721} A succe
246d0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
246e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
246f0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
24700 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
24710 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24720 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24730 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
24740 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
24750 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
24760 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
24770 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
24780 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
24790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
247a0 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
247b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
247c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
247d0 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73  H13723} A succes
247e0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
247f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
24800 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
24810 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
24820 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24830 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24840 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
24850 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
24860 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
24870 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
24880 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
24890 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
248a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
248b0 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
248c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
248d0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  16 string.**    
248e0 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
248f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
24900 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54  **.** {H13724} T
24910 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24920 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b  mn_name()] and [
24930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24940 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ame16()].**     
24950 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
24960 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
24970 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72  inter if they ar
24980 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20  e unable to.**  
24990 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
249a0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
249b0 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
249c0 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
249d0 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74  ** {H13725} If t
249e0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
249f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
24a00 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
24a10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24a30 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
24a40 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
24a50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
24a60 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
24a70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
24a80 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20  .**.** {H13726} 
24a90 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
24aa0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
24ab0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
24ac0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
24ad0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24ae0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
24af0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
24b00 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20  the next.**     
24b10 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74       call to eit
24b20 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68  her routine with
24b30 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20   the same S and 
24b40 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
24b50 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
24b60 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  l [sqlite3_final
24b70 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
24b80 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37  d..**.** {H13727
24b90 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  } When a result 
24ba0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
24bb0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
24bc0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
24bd0 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65      an AS clause
24be0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
24bf0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  at column is the
24c00 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20   identifier.**  
24c10 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
24c20 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
24c30 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
24c40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
24c50 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
24c60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
24c70 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24c80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24c90 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
24ca0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
24cb0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
24cc0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
24cd0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
24ce0 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3740} <S10700>.*
24cf0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24d00 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
24d10 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
24d20 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
24d30 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
24d40 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
24d50 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53  a result of a [S
24d60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
24d70 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
24d80 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
24d90 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
24da0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
24db0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
24dc0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
24dd0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
24de0 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
24df0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
24e00 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
24e10 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
24e20 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
24e30 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
24e40 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
24e50 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
24e60 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
24e70 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
24e80 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24e90 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
24ea0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24eb0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
24ec0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
24ed0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24ee0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
24ef0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
24f00 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
24f10 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
24f20 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
24f30 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
24f40 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
24f50 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
24f60 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
24f70 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
24f80 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
24f90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
24fa0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
24fb0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
24fc0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
24fd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
24fe0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
24ff0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
25000 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
25010 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
25020 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
25030 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
25040 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
25050 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
25060 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
25070 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
25080 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
25090 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
250a0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
250b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
250c0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
250d0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
250e0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
250f0 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  * NULL.  These r
25100 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
25110 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
25120 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
25130 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
25140 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
25150 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
25160 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
25170 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
25180 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f   table.** and co
25190 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
251a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
251b0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
251c0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
251d0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
251e0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
251f0 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
25200 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
25210 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
25220 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
25230 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
25240 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
25250 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
25260 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
25270 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
25280 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
25290 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
252a0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
252b0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
252c0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
252d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  ined..**.** {A13
252e0 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
252f0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
25300 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
25310 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
25320 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
25330 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
25340 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
25350 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
25360 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
25370 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
25380 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
25390 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
253a0 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {H13741} The [sq
253b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
253c0 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
253d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
253e0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
253f0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
25400 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
25410 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
25420 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
25430 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
25440 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
25450 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
25460 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25470 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
25480 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
25490 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
254a0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
254b0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
254c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
254d0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
254e0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
254f0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25500 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54  **.** {H13742} T
25510 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25520 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25530 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
25540 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
25550 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
25560 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
25570 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
25580 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
25590 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
255a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
255b0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
255c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
255d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
255e0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
255f0 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
25600 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
25610 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25620 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
25630 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
25640 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
25650 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25660 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
25670 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
25680 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {H13743} The [s
25690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
256a0 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
256b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
256c0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
256d0 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
256e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
256f0 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
25700 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
25710 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
25720 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
25730 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25740 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
25750 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
25760 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
25770 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25780 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
25790 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
257a0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
257b0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
257c0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
257d0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
257e0 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {H13744} The [s
257f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
25800 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
25810 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25820 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
25830 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
25840 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
25850 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
25860 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
25870 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
25880 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
25890 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
258a0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
258b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
258c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
258d0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
258e0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
258f0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
25900 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
25910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25920 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25930 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25940 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
25950 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54  **.** {H13745} T
25960 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
25970 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
25980 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25990 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
259a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
259b0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
259c0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
259d0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
259e0 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
259f0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
25a00 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
25a10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25a20 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
25a30 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
25a40 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
25a50 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
25a60 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
25a70 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
25a80 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
25a90 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
25aa0 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
25ab0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
25ac0 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
25ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25ae0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
25af0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25b00 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
25b10 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
25b20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
25b30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
25b40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
25b50 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  le.**          c
25b60 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
25b70 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
25b80 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
25b90 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
25ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25bb0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
25bc0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
25bd0 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  h column.**     
25be0 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67       of S is a g
25bf0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
25c00 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
25c10 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
25c20 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
25c30 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
25c40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20  .**.** {H13748} 
25c50 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
25c60 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
25c70 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
25c80 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25c90 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
25ca0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
25cb0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
25cc0 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66  alid for the lif
25cd0 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72  etime of the [pr
25ce0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25cf0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
25d00 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64   until the encod
25d10 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62  ing is changed b
25d20 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61  y another metada
25d30 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ta.**          i
25d40 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f  nterface call fo
25d50 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61  r the same prepa
25d60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
25d70 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
25d80 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
25d90 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74  ** {A13751} If t
25da0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
25db0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
25dc0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
25dd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25de0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
25df0 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
25e00 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
25e10 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
25e20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
25e30 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
25e40 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
25e50 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
25e60 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
25e70 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
25e80 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
25e90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25ea0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
25eb0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25ec0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25ed0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25ee0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25ef0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25f00 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
25f10 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25f20 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
25f30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25f40 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
25f60 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
25f70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25f80 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25f90 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
25fa0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25fb0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25fc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25fd0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
25fe0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25ff0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
26000 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
26010 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
26020 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
26030 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
26040 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
26050 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
26060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26070 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
26080 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
26090 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
260a0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
260b0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
260c0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
260d0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
260e0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
260f0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
26100 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
26110 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
26120 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
26130 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
26140 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
26150 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
26160 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
26170 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
26180 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
26190 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
261a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
261b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
261c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
261d0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
261e0 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
261f0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
26200 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
26210 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
26220 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
26230 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
26240 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
26250 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
26260 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
26270 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
26280 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
26290 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
262a0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
262b0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
262c0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
262d0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
262e0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
262f0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
26300 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
26310 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
26320 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
26330 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
26340 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
26350 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
26360 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
26370 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
26380 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
26390 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
263a0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
263b0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
263c0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
263d0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
263e0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
263f0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
26400 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
26410 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
26420 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
26430 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
26440 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
26450 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
26460 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
26470 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
26480 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
26490 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
264a0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20  **.** {H13761}  
264b0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
264c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
264d0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
264e0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  N)] returns a.**
264f0 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d             zero-
26500 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
26510 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
26520 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
26530 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20  datatype.**     
26540 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62        of the tab
26550 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
26560 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74  ppears as the Nt
26570 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
26580 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
26590 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
265a0 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
265b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
265c0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
265d0 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  H13762}  A succe
265e0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
265f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
26600 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
26610 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
26620 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
26630 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
26640 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
26650 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
26660 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
26670 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
26680 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
26690 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
266a0 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
266b0 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
266c0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
266d0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
266e0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
266f0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
26700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26710 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
26720 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
26730 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
26740 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
26750 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
26760 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
26770 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
26780 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26790 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
267a0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68          or if th
267b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
267c0 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  S is an expressi
267d0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72  on or subquery r
267e0 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ather.**        
267f0 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20     than a table 
26800 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20  column, or if a 
26810 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
26820 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20  n failure.**    
26830 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
26840 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f  ring encoding co
26850 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a  nversions, then.
26860 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c  **           cal
26870 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
26880 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
26890 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
268a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
268b0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
268c0 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c  S,N)] return NUL
268d0 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  L..*/.const char
268e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
268f0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
26900 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
26910 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
26920 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
26930 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
26940 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
26950 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
26960 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
26970 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30  nt {H13200} <S10
26980 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  000>.**.** After
26990 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
269a0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
269b0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
269c0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
269d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
269e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
269f0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
26a00 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
26a10 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
26a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26a30 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
26a40 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
26a50 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
26a60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
26a70 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
26a80 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
26a90 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
26aa0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
26ab0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
26ac0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
26ad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
26ae0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
26af0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
26b00 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
26b10 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
26b20 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
26b30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26b40 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
26b50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26b60 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
26b70 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26b80 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
26b90 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
26ba0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26bb0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
26bc0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
26bd0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
26be0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
26bf0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
26c00 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
26c10 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
26c20 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
26c30 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
26c40 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
26c50 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
26c60 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
26c70 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
26c80 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
26c90 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
26ca0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
26cb0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
26cc0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
26cd0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
26ce0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
26cf0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
26d00 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
26d10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
26d20 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
26d30 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
26d40 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
26d50 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
26d60 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
26d70 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
26d80 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
26d90 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
26da0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
26db0 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
26dc0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
26dd0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
26de0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
26df0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
26e00 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
26e10 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
26e20 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
26e30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26e40 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
26e50 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
26e60 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
26e70 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
26e80 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
26e90 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
26ea0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
26eb0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
26ec0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
26ed0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
26ee0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
26ef0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
26f00 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
26f10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26f20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
26f30 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
26f40 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
26f50 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
26f60 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
26f70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
26f80 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
26f90 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
26fa0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
26fb0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
26fc0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
26fd0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
26fe0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
26ff0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
27000 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
27010 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
27020 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
27030 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
27040 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
27050 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
27060 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
27070 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
27080 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
27090 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
270a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
270b0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
270c0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
270d0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
270e0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  **.** [SQLITE_ER
270f0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
27100 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
27110 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
27120 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
27130 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
27140 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
27150 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
27160 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
27170 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
27180 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
27190 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
271a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
271b0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68  rmsg()]..** With
271c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
271d0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
271e0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
271f0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
27200 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
27210 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
27220 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
27230 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
27240 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
27250 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
27260 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
27270 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
27280 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27290 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
272a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
272b0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
272c0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
272d0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
272e0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
272f0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
27300 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
27310 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
27320 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
27330 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
27340 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
27350 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
27360 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
27370 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
27380 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
27390 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
273a0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
273b0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
273c0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
273d0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
273e0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
273f0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
27400 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
27410 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
27420 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
27430 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
27440 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
27450 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
27460 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
27470 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
27480 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
27490 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
274a0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
274b0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
274c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
274d0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
274e0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
274f0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
27500 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
27510 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
27520 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
27530 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
27540 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
27550 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
27560 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27570 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
27580 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
27590 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
275a0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
275b0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
275c0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
275d0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
275e0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
275f0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
27600 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
27610 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
27620 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
27630 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27640 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
27650 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
27660 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
27670 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
27680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27690 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
276a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
276b0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
276c0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
276d0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
276e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
276f0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
27700 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
27710 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
27720 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
27730 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
27740 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
27750 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
27760 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
27770 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
27780 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
27790 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
277a0 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20  H13202}  If the 
277b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
277c0 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
277d0 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a  to be run, then.
277e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
277f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
27800 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
27810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27820 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
27830 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72     completion or
27840 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61   until it is rea
27850 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f  dy to return ano
27860 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a  ther row of the.
27870 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73  **           res
27880 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69  ult set, or unti
27890 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l an [sqlite3_in
278a0 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
278b0 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  upt].**         
278c0 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20    or a run-time 
278d0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
278e0 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68  .** {H15304}  Wh
278f0 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
27900 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
27910 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61  auses the [prepa
27920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27930 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f  *           S to
27940 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
27950 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  on, the function
27960 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
27970 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DONE]..**.** {H
27980 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
27990 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
279a0 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
279b0 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
279c0 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  dy to.**        
279d0 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65     return anothe
279e0 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
279f0 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
27a00 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
27a10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d  ..**.** {H15308}
27a20 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b    If a call to [
27a30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27a40 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a   encounters an.*
27a50 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27a60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
27a70 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
27a80 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
27a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
27aa0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
27ab0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
27ac0 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
27ad0 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
27ae0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
27af0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
27b00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
27b10 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20  **.** {H15310}  
27b20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
27b30 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
27b40 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74  rupt] or a run-t
27b50 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
27b60 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
27b70 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
27b80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
27ba0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
27bb0 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
27bc0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
27bd0 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
27be0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
27bf0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
27c00 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27c10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27c20 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  ], then the func
27c30 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
27c40 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
27c50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
27c60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
27c70 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
27c80 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
27c90 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
27ca0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
27cb0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27cc0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
27cd0 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37  result set {H137
27ce0 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  70} <S10700>.**.
27cf0 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e  ** Returns the n
27d00 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
27d10 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
27d20 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
27d30 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   set..**.** INVA
27d40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
27d50 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20  13771}  After a 
27d60 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27d70 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72  _step(S)] that r
27d80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
27d90 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  OW],.**         
27da0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    the [sqlite3_d
27db0 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f  ata_count(S)] ro
27dc0 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
27dd0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
27de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
27df0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
27e00 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
27e10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
27e20 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  H13772}  After [
27e30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27e40 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
27e50 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
27e60 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
27e70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
27e80 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
27e90 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
27ea0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a  n called on the.
27eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
27ec0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27ed0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
27ee0 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
27ef0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
27f00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
27f10 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b  | prepared] or [
27f20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20  sqlite3_reset | 
27f30 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20  reset],.**      
27f40 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
27f50 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
27f60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27f70 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
27f80 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27f90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27fa0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27fb0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
27fc0 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48  tal Datatypes {H
27fd0 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c  10265} <S10110><
27fe0 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10120>.** KEYWO
27ff0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
28000 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20  .**.** {H10266} 
28010 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
28020 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
28030 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
28040 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
28050 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
28060 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
28070 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
28080 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
28090 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
280a0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
280b0 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
280c0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
280d0 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
280e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
280f0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
28100 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
28110 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
28120 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
28130 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
28140 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
28150 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
28160 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
28170 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
28180 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
28190 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
281a0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
281b0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
281c0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
281d0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
281e0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
281f0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
28200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
28210 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
28220 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
28230 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
28240 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
28250 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
28260 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
28270 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
28280 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
28290 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
282a0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
282b0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
282c0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
282d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
282e0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
282f0 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33  rom A Query {H13
28300 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  800} <S10700>.**
28310 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
28320 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
28330 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
28340 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
28350 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71  he "result set q
28360 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e  uery" interface.
28370 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28380 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
28390 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
283a0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
283b0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
283c0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
283d0 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72   query.  In ever
283e0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
283f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
28400 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
28410 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28420 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
28430 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
28440 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
28450 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
28460 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
28470 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28480 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
28490 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
284a0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
284b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
284c0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
284d0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
284e0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
284f0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
28500 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
28510 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
28520 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
28530 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  dex 0..**.** If 
28540 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
28550 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
28560 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
28570 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
28580 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
28590 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
285a0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
285b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
285c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
285d0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
285e0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
285f0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
28600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28610 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
28620 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
28630 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
28640 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28650 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
28660 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
28670 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
28680 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
28690 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
286a0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
286b0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
286c0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
286d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
286e0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
286f0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
28700 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
28710 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
28720 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
28730 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
28740 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
28750 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28760 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
28770 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
28780 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
28790 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
287a0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
287b0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
287c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
287d0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
287e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
287f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
28800 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28810 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
28820 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28830 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
28840 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
28850 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
28860 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
28870 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
28880 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
28890 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
288a0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
288b0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
288c0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
288d0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
288e0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
288f0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
28900 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
28910 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
28920 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
28930 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
28940 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
28950 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
28960 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
28970 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
28980 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
28990 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
289a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
289b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
289c0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
289d0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
289e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
289f0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
28a00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
28a10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28a20 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
28a30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
28a40 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
28a50 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
28a60 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
28a70 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
28a80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28a90 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
28aa0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
28ab0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
28ac0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
28ad0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
28ae0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
28af0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
28b00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28b10 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
28b20 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
28b30 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
28b40 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
28b50 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
28b60 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
28b70 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
28b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28b90 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
28ba0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
28bb0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
28bc0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
28bd0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
28be0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
28bf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28c00 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
28c10 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
28c20 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
28c30 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
28c40 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
28c50 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
28c60 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
28c70 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
28c80 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
28c90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
28ca0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
28cb0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28cc0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
28cd0 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
28ce0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28cf0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
28d00 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28d10 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
28d20 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
28d30 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
28d40 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
28d50 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
28d60 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
28d70 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
28d80 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
28d90 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69   BLOB is an arbi
28da0 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
28db0 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
28dc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
28dd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28de0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
28df0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
28e00 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
28e10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
28e20 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
28e30 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
28e40 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
28e50 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
28e60 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65  of UTF-8..** The
28e70 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28e80 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
28e90 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
28ea0 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74  **.** The object
28eb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
28ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
28ed0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
28ee0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28ef0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28f00 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
28f10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28f20 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
28f30 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
28f40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
28f50 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
28f60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
28f70 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
28f80 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
28f90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28fa0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
28fb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
28fc0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
28fd0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
28fe0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
28ff0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
29000 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
29010 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
29020 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
29030 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
29040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
29050 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
29060 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
29070 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
29080 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
29090 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
290a0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
290b0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
290c0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
290d0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
290e0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
290f0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
29100 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
29110 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
29120 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
29130 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
29140 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
29150 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
29160 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
29170 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
29180 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
29190 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
291a0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
291b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
291c0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
291d0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
291e0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
291f0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
29200 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
29210 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
29220 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
29230 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
29240 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
29250 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
29260 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
29270 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
29280 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
29290 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
292a0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
292b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
292c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
292d0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
292e0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
292f0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
29300 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
29310 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
29320 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
29330 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
29340 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
29350 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
29360 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
29370 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
29380 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
29390 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
293a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
293b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
293c0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
293d0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
293e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
293f0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
29400 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
29410 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
29420 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
29430 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
29440 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
29450 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
29460 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
29470 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
29480 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
29490 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
294a0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
294b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
294c0 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
294d0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
294e0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
294f0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
29500 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
29510 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
29520 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
29530 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
29540 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
29550 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29560 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
29570 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
29580 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
29590 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
295a0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
295b0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
295c0 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
295d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
295e0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
295f0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
29600 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
29610 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
29620 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
29630 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
29640 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
29650 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
29660 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
29670 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
29680 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
29690 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
296a0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
296b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
296c0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
296d0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
296e0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
296f0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
29700 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
29710 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
29720 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
29730 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
29740 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
29750 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
29760 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
29770 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
29780 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
29790 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
297a0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
297b0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
297c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
297d0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
297e0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
297f0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
29800 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
29810 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
29820 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
29830 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
29840 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
29850 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
29860 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
29870 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
29880 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29890 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
298a0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
298b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
298c0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
298d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
298e0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
298f0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
29900 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
29910 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
29920 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
29930 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
29940 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
29950 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
29960 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29970 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
29980 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
29990 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
299a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
299b0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
299c0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
299d0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
299e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
299f0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29a00 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
29a10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29a20 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
29a30 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
29a40 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
29a50 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
29a60 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
29a70 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
29a80 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
29a90 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73  l>.**.** Convers
29aa0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
29ab0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
29ac0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
29ad0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
29ae0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
29af0 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
29b00 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
29b10 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
29b20 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
29b30 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
29b40 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
29b50 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
29b60 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
29b70 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
29b80 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
29b90 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
29ba0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
29bb0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
29bc0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
29bd0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
29be0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
29bf0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
29c00 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
29c10 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
29c20 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
29c30 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
29c40 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
29c50 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
29c60 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
29c70 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
29c80 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
29c90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29ca0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
29cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29cc0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
29cd0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
29ce0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
29cf0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29d00 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
29d10 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
29d20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29d30 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
29d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29d50 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
29d60 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
29d70 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
29d80 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
29d90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
29da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29db0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
29dc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29dd0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
29de0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
29df0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
29e00 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
29e10 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
29e20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
29e30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
29e40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
29e50 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
29e60 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
29e70 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
29e80 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
29e90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
29ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29eb0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
29ec0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
29ed0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
29ee0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
29ef0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
29f00 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
29f10 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
29f20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29f30 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
29f40 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
29f50 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
29f60 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
29f70 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
29f80 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
29f90 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
29fa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
29fb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
29fc0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29fd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29fe0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
29ff0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2a000 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2a010 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2a020 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2a030 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2a040 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2a050 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2a060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2a070 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2a080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a090 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2a0a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2a0b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
2a0c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2a0d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2a0e0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2a0f0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2a100 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2a110 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2a120 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2a130 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2a140 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2a150 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2a160 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2a170 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2a180 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2a190 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2a1a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2a1b0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2a1c0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2a1d0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
2a1e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2a1f0 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b  * {H13803} The [
2a200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a210 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(S,N)] interf
2a220 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2a230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2a240 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2a250 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2a260 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2a270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2a280 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a290 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42  ment] S into a B
2a2a0 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74  LOB and then ret
2a2b0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
2a2c0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
2a2d0 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
2a2e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36  e..**.** {H13806
2a2f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a300 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
2a310 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a320 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
2a330 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
2a340 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20  tes in the BLOB 
2a350 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
2a360 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
2a370 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
2a380 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
2a390 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
2a3a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2a3b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
2a3c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2a3d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a3e0 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
2a3f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2a400 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
2a410 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
2a420 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
2a430 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a440 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2a450 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2a460 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
2a470 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2a480 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
2a490 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
2a4a0 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
2a4b0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
2a4c0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
2a4d0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2a4e0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
2a4f0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a510 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
2a520 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {H13812} The [s
2a530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a540 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
2a550 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2a560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2a570 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2a580 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2a590 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2a5a0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2a5b0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a5c0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2a5d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2a5e0 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
2a5f0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2a600 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
2a610 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35  e..**.** {H13815
2a620 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a630 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
2a640 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a650 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a660 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a670 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a680 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a690 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
2a6a0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a6b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2a6c0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2a6d0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2a6e0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2a6f0 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
2a700 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
2a710 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eger..**.** {H13
2a720 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  818} The [sqlite
2a730 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53  3_column_int64(S
2a740 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2a750 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2a760 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2a770 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2a780 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2a790 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
2a7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2a7b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a7c0 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
2a7d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2a7e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2a7f0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2a800 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
2a810 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54  **.** {H13821} T
2a820 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2a830 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e  mn_text(S,N)] in
2a840 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2a850 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a860 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2a870 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2a880 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2a890 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2a8a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a8b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2a8c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a8d0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
2a8e0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2a8f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2a900 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2a910 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d  ..**.** {H13824}
2a920 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a930 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29  lumn_text16(S,N)
2a940 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2a950 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2a960 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2a970 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2a980 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a990 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2a9a0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2a9b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a9c0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2a9d0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2a9e0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2a9f0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2aa00 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
2aa10 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2aa20 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
2aa30 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2aa40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
2aa50 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2aa60 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
2aa70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2aa80 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2aa90 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2aaa0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2aab0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2aac0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2aad0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2aae0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2aaf0 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2ab00 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2ab10 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
2ab20 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2ab30 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ab40 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2ab50 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2ab60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ab70 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30  S..**.** {H13830
2ab80 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2ab90 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29  olumn_value(S,N)
2aba0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2abb0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2abc0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20    pointer to an 
2abd0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2abe0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2abf0 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ct for the.**   
2ac00 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2ac10 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2ac20 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ac30 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2ac40 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2ac50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ac60 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  S..*/.const void
2ac70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ac80 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2ac90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2aca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2acb0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2acc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2acd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2ace0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2acf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ad00 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2ad10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2ad20 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2ad30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2ad40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2ad50 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2ad60 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ad70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2ad80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2ad90 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2ada0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2adb0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2adc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2add0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2ade0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2adf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ae00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ae10 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2ae20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2ae30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ae40 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2ae50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2ae60 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2ae70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ae80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ae90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2aea0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2aeb0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2aec0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2aed0 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30   {H13300} <S7030
2aee0 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
2aef0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
2af00 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2af10 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2af20 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2af30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2af40 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2af50 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
2af60 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
2af70 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
2af80 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
2af90 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
2afa0 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  . If execution o
2afb0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2afc0 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a  failed then an.*
2afd0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
2afe0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2aff0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2b000 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
2b010 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2b020 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2b030 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
2b040 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
2b050 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2b060 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20  ement].  If the 
2b070 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2b080 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
2b090 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
2b0a0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
2b0b0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
2b0c0 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
2b0d0 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
2b0e0 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
2b0f0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
2b100 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f  errupt]..** Inco
2b110 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
2b120 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
2b130 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
2b140 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
2b150 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2b160 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
2b170 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
2b180 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
2b190 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
2b1a0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
2b1b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2b1c0 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {H11302} The [s
2b1d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b1e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
2b1f0 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
2b200 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2b210 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
2b220 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
2b230 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
2b240 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
2b250 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
2b260 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
2b270 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {H11304} If the 
2b280 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2b290 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b2a0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2b2b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2b2c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b2d0 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
2b2e0 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
2b2f0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
2b300 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
2b310 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
2b320 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
2b330 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2b340 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b350 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b360 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2b370 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2b380 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53  ject {H13330} <S
2b390 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70300>.**.** The
2b3a0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2b3b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2b3c0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2b3d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b3e0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2b3f0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2b400 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2b410 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2b420 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
2b430 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2b440 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2b450 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2b460 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2b470 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2b480 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2b490 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2b4a0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2b4b0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2b4c0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2b4d0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2b4e0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ngs..**.** {H113
2b4f0 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
2b500 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2b510 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2b520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b530 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
2b540 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
2b550 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2b560 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
2b570 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  H11334} If the m
2b580 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2b590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2b5a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2b5b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2b5c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2b5d0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2b5e0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2b5f0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
2b600 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
2b610 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2b620 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2b630 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2b640 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2b650 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b660 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2b670 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
2b680 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
2b690 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2b6a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2b6b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2b6c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2b6d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2b6e0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2b6f0 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
2b700 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2b710 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2b720 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2b730 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2b740 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b  * {H11338} The [
2b750 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b760 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2b770 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2b780 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
2b790 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
2b7a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
2b7b0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
2b7c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b7d0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
2b7e0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2b7f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b810 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2b820 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2b830 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30  ns {H16100} <S20
2b840 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
2b850 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2b860 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2b870 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b880 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2b8a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b8b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b8c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2b8d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
2b8e0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2b8f0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2b900 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2b910 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2b920 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2b930 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2b940 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2b950 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2b960 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2b970 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2b980 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2b990 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2b9a0 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
2b9b0 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
2b9c0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
2b9d0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
2b9e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
2b9f0 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
2ba00 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
2ba10 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
2ba20 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
2ba30 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2ba40 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
2ba50 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2ba60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
2ba70 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2ba80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2ba90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2baa0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2bab0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2bac0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2bad0 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
2bae0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
2baf0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
2bb00 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2bb10 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74  on internally, t
2bb20 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  hen SQL function
2bb30 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
2bb40 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a  individually to.
2bb50 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65  ** each database
2bb60 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
2bb70 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
2bb80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2bb90 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2bba0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2bbb0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2bbc0 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67  fined.  The leng
2bbd0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2bbe0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2bbf0 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
2bc00 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
2bc10 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
2bc20 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2bc30 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2bc40 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
2bc50 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41  * characters.  A
2bc60 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2bc70 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2bc80 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2bc90 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2bca0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
2bcb0 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
2bcc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  ed..**.** The th
2bcd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
2bce0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2bcf0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2bd00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2bd10 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2bd20 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
2bd30 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
2bd40 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
2bd50 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2bd60 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2bd70 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2bd80 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
2bd90 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
2bda0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2bdb0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2bdc0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2bdd0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2bde0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2bdf0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2be00 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2be10 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
2be20 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2be30 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
2be40 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2be50 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
2be60 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2be70 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2be80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2be90 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2bea0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2beb0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2bec0 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
2bed0 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
2bee0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2bef0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2bf00 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2bf10 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2bf20 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2bf30 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2bf40 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2bf50 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2bf60 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2bf70 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
2bf80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2bf90 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2bfa0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2bfb0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2bfc0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2bfd0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2bfe0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2bff0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2c000 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2c010 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2c020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2c030 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2c040 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2c050 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2c060 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2c070 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2c080 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2c090 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
2c0a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2c0b0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2c0c0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2c0d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2c0e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2c0f0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2c100 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2c110 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2c120 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
2c130 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
2c140 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
2c150 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2c160 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2c170 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2c180 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2c190 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2c1a0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2c1b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2c1c0 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
2c1d0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2c1e0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2c1f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2c200 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2c210 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
2c220 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
2c230 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2c240 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2c250 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2c260 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
2c270 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2c280 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2c290 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2c2a0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2c2b0 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
2c2c0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2c2d0 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  c. To delete an 
2c2e0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2c2f0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2c300 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2c310 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2c320 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2c330 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
2c340 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2c350 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2c360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2c370 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2c380 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2c390 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2c3a0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2c3b0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2c3c0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2c3d0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2c3e0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2c3f0 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
2c400 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2c410 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
2c420 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2c430 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2c440 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2c450 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
2c460 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2c470 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68  *.** {H16103} Th
2c480 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2c490 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2c4a0 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65  interface behave
2c4b0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
2c4c0 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69        like [sqli
2c4d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c4e0 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20  ion()] in every 
2c4f0 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20  way except that 
2c500 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  it.**          i
2c510 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46  nterprets the zF
2c520 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75  unctionName argu
2c530 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72  ment as zero-ter
2c540 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a  minated UTF-16.*
2c550 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76  *          nativ
2c560 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2c570 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d  tead of as zero-
2c580 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2c590 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d  ..**.** {H16106}
2c5a0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
2c5b0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  vocation of.**  
2c5c0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2c5d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c5e0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2c5f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
2c600 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  isters.**       
2c610 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
2c620 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2c630 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s in the [databa
2c640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2c650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
2c660 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  d to implement t
2c670 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c680 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70  named X with N p
2c690 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
2c6a0 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67        and having
2c6b0 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78   a preferred tex
2c6c0 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e  t encoding of E.
2c6d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20  .**.** {H16109} 
2c6e0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2c6f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2c700 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2c710 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2c720 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6c  **          repl
2c730 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53  aces the P, F, S
2c740 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66  , and L values f
2c750 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61  rom any prior ca
2c760 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  lls with.**     
2c770 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c       the same D,
2c780 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c   X, N, and E val
2c790 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ues..**.** {H161
2c7a0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2c7b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c7c0 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  (D,X,...)] inter
2c7d0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a  face fails with.
2c7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
2c7f0 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51  turn code of [SQ
2c800 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74  LITE_ERROR] if t
2c810 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c820 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20  name X is.**    
2c830 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61        longer tha
2c840 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c  n 255 bytes excl
2c850 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2c860 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2c870 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45 69 74  .** {H16118} Eit
2c880 68 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55  her F must be NU
2c890 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61  LL and S and L a
2c8a0 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65  re non-NULL or e
2c8b0 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20  lse F.**        
2c8c0 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e    is non-NULL an
2c8d0 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55  d S and L are NU
2c8e0 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  LL, otherwise.**
2c8f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c900 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c910 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2c920 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  ,L)] returns [SQ
2c930 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a  LITE_ERROR]..**.
2c940 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20  ** {H16121} The 
2c950 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c960 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d  function(D,...)]
2c970 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2c980 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
2c990 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
2c9a0 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  of [SQLITE_BUSY]
2c9b0 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20   if there exist 
2c9c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c9d0 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ents].**        
2c9e0 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74    associated wit
2c9f0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2ca00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2ca10 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68  *.** {H16124} Th
2ca20 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2ca30 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2ca40 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2ca50 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
2ca60 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
2ca70 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2ca80 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d  _ERROR] if param
2ca90 65 74 65 72 20 4e 20 28 73 70 65 63 69 66 79 69  eter N (specifyi
2caa0 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ng the number.**
2cab0 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 72 67            of arg
2cac0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2cad0 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  L function being
2cae0 20 72 65 67 69 73 74 65 72 65 64 29 20 69 73 20   registered) is 
2caf0 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
2cb00 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2cb10 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a  ter than 127..**
2cb20 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65  .** {H16127} Whe
2cb30 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  n N is non-negat
2cb40 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ive, the [sqlite
2cb50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cb60 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2cb70 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2cb80 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62  ace causes callb
2cb90 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b  acks to be invok
2cba0 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66  ed for the SQL f
2cbb0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2cbc0 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e      named X when
2cbd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2cbe0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2cbf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  SQL function is.
2cc00 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63  **          exac
2cc10 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tly N..**.** {H1
2cc20 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20  6130} When N is 
2cc30 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  -1, the [sqlite3
2cc40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2cc50 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2cc60 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2cc70 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61  ce causes callba
2cc80 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  cks to be invoke
2cc90 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75  d for the SQL fu
2cca0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2ccb0 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20     named X with 
2ccc0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2ccd0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  guments..**.** {
2cce0 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c  H16133} When cal
2ccf0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
2cd00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2cd10 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2cd20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d         specify m
2cd30 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2cd40 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2cd50 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ame function X.*
2cd60 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77  *          and w
2cd70 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e  hen one implemen
2cd80 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20  tation has N>=0 
2cd90 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61  and the other ha
2cda0 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20  s N=(-1).**     
2cdb0 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65       the impleme
2cdc0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2cdd0 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65  on-zero N is pre
2cde0 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2cdf0 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c  16136} When call
2ce00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2ce10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ce20 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  X,N,E,...)].**  
2ce30 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2ce40 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2ce50 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2ce60 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20  same function X 
2ce70 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2ce80 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
2ce90 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
2cea0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2ceb0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  nt.**          e
2cec0 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e  ncodings E, then
2ced0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2cee0 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63  ion where E matc
2cef0 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hes the.**      
2cf00 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63      database enc
2cf10 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65 72 72  oding is preferr
2cf20 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ed..**.** {H1613
2cf30 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67  9} For an aggreg
2cf40 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2cf50 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
2cf60 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2cf70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2cf80 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c  ion(D,X,N,E,P,0,
2cf90 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69  S,L)] the finali
2cfa0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
2cfb0 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20  function L will 
2cfc0 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65  always be invoke
2cfd0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69  d exactly once i
2cfe0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2cff0 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20    step function 
2d000 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20  S is called one 
2d010 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2d020 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68  *.** {H16142} Wh
2d030 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
2d040 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75  s either the xFu
2d050 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63  nc or xStep func
2d060 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
2d070 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69      an applicati
2d080 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d090 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2d0a0 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  gate created.** 
2d0b0 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
2d0c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d0d0 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  tion()] or [sqli
2d0e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d0f0 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  ion16()],.**    
2d100 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61        then the a
2d110 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33  rray of [sqlite3
2d120 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20  _value] objects 
2d130 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
2d140 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20            third 
2d150 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c  parameter are al
2d160 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20  ways [protected 
2d170 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d180 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73  bjects..*/.int s
2d190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d1a0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2d1b0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2d1c0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2d1d0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2d1e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2d1f0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2d200 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2d210 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2d220 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2d230 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2d240 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2d250 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2d260 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2d270 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2d280 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2d290 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2d2a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2d2b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2d2c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2d2d0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2d2e0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2d2f0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2d300 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2d310 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2d320 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2d330 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2d340 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2d350 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2d360 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2d370 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2d380 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2d390 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
2d3a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2d3b0 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32   Encodings {H102
2d3c0 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31  67} <S50200> <H1
2d3d0 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6100>.**.** Thes
2d3e0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2d3f0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2d400 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2d410 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2d420 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2d430 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2d440 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2d450 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2d460 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2d470 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2d480 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2d490 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2d4a0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2d4b0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2d4c0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2d4d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2d4e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2d4f0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2d500 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2d510 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d520 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2d530 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2d540 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2d550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2d560 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2d570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d580 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2d590 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2d5a0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2d5b0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2d5c0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2d5d0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2d5e0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2d5f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2d600 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2d610 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2d620 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2d630 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2d640 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2d650 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2d660 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2d670 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2d680 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2d690 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2d6a0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2d6b0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2d6c0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2d6d0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
2d6e0 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 53  nt they do..*/.S
2d6f0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2d700 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
2d710 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2d720 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2d730 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2d740 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
2d750 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2d760 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2d770 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2d780 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2d790 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2d7a0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2d7b0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2d7c0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2d7d0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2d7e0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2d7f0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
2d800 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2d810 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
2d820 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2d830 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2d840 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2d850 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2d860 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2d870 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2d880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d890 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
2d8a0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
2d8b0 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30  r Values {H15100
2d8c0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
2d8d0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
2d8e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2d8f0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
2d900 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
2d910 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
2d920 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
2d930 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
2d940 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
2d950 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
2d960 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2d970 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
2d980 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
2d990 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
2d9a0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
2d9b0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
2d9c0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2d9d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d9e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d9f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2da00 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
2da10 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
2da20 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2da30 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2da40 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
2da50 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2da60 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
2da70 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
2da80 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
2da90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2daa0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2dab0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
2dac0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2dad0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
2dae0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
2daf0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
2db00 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
2db10 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
2db20 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
2db30 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
2db40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2db50 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
2db60 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
2db70 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
2db80 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2db90 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
2dba0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
2dbb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2dbc0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
2dbd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dbe0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
2dbf0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
2dc00 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2dc10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2dc20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
2dc30 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2dc40 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2dc50 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
2dc60 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
2dc70 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
2dc80 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
2dc90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dca0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
2dcb0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
2dcc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2dcd0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
2dce0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
2dcf0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  umber..**.** The
2dd00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2dd10 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2dd20 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2dd30 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2dd40 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2dd50 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2dd60 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
2dd70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2dd80 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2dd90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2dda0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2ddb0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2ddc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2ddd0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2dde0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2ddf0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2de00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2de10 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2de20 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2de30 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2de40 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2de50 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2de60 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2de70 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2de80 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2de90 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2dea0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2deb0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2dec0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2ded0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2dee0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2def0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2df00 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2df10 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2df20 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2df30 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2df40 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2df50 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2df60 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2df70 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2df80 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2df90 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2dfa0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2dfb0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2dfc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2dfd0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2dfe0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2dff0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2e000 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2e010 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2e020 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2e030 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2e040 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2e050 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2e060 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2e070 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2e080 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2e090 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2e0a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2e0b0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2e0c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2e0d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e0e0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2e0f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e100 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2e110 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2e120 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2e130 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2e140 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2e150 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2e160 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2e170 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2e180 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
2e190 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2e1a0 2a 20 7b 48 31 35 31 30 33 7d 20 54 68 65 20 5b  * {H15103} The [
2e1b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2e1c0 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  ob(V)] interface
2e1d0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2e1e0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2e1f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e200 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2e210 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65  o a BLOB and the
2e220 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  n.**          re
2e230 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2e240 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
2e250 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   value..**.** {H
2e260 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  15106} The [sqli
2e270 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2e280 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2e290 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2e2a0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2e2b0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
2e2c0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
2e2d0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2e2e0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2e2f0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2e300 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2e310 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2e320 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2e330 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2e340 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
2e350 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20  _blob(V)] or.** 
2e360 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2e370 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2e380 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d  ..**.** {H15109}
2e390 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e3a0 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20  lue_bytes16(V)] 
2e3b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e3c0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2e3d0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2e3e0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2e3f0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2e400 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2e410 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2e420 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2e430 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2e440 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2e450 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2e460 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2e470 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c  alue_text16(V)],
2e480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2e490 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e4a0 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71  16be(V)], or [sq
2e4b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e4c0 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16le(V)]..**.** 
2e4d0 7b 48 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71  {H15112} The [sq
2e4e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2e4f0 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2e500 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2e510 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2e520 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e530 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2e540 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2e550 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2e560 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2e570 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2e580 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2e590 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  5115} The [sqlit
2e5a0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d  e3_value_int(V)]
2e5b0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e5c0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e5d0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e5f0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
2e600 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2e610 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2e620 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2e630 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2e640 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2e650 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54 68  *.** {H15118} Th
2e660 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2e670 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72  _int64(V)] inter
2e680 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2e690 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2e6a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e6b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2e6c0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
2e6d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2e6e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2e6f0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2e700 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2e710 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 68 65  .** {H15121} The
2e720 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e730 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61  text(V)] interfa
2e740 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2e750 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2e760 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e770 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2e780 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2e790 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20  nated UTF-8.**  
2e7a0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2e7b0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2e7c0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2e7d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ing..**.** {H151
2e7e0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2e7f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29  _value_text16(V)
2e800 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2e810 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2e820 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2e830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e840 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2e850 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2e860 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2e870 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2e880 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2e890 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
2e8a0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2e8b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2e8c0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2e8d0 2a 20 7b 48 31 35 31 32 37 7d 20 54 68 65 20 5b  * {H15127} The [
2e8e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e8f0 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
2e900 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2e910 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2e920 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e930 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2e940 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2e950 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2e960 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2e970 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
2e980 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2e990 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e9a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e9b0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2e9c0 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 68 65  .** {H15130} The
2e9d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e9e0 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
2e9f0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2ea00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ea10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2ea20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ea30 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2ea40 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2ea50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2ea60 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74  gned UTF-16 litt
2ea70 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
2ea80 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2ea90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2eaa0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2eab0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33  g..**.** {H15133
2eac0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2ead0 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e  alue_type(V)] in
2eae0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2eaf0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2eb00 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2eb10 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2eb20 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2eb30 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2eb40 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2eb50 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2eb60 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2eb70 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2eb80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2eb90 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a  e] object V..**.
2eba0 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 65 20  ** {H15136} The 
2ebb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e  [sqlite3_value_n
2ebc0 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20  umeric_type(V)] 
2ebd0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2ebe0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ts.**          t
2ebf0 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  he [protected sq
2ec00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ec10 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65  ect V into eithe
2ec20 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a  r an integer or.
2ec30 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c  **          a fl
2ec40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ec50 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20  ue if it can do 
2ec60 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  so without loss 
2ec70 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  of.**          i
2ec80 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20  nformation, and 
2ec90 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b  returns one of [
2eca0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a  SQLITE_NULL],.**
2ecb0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2ecc0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2ecd0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2ece0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a  ITE_TEXT], or.**
2ecf0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2ed00 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2ed10 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a  priate for the.*
2ed20 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2ed30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ed40 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66  lue] object V af
2ed50 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ter the conversi
2ed60 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63  on attempt..*/.c
2ed70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ed80 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2ed90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2eda0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2edb0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2edc0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2edd0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2ede0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2edf0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2ee00 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2ee10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ee20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2ee30 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2ee40 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2ee50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2ee60 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2ee70 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ee80 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2ee90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2eea0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2eeb0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2eec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2eed0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2eee0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2eef0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2ef00 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2ef10 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2ef20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2ef30 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2ef40 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2ef50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2ef60 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2ef70 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2ef80 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2ef90 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2efa0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2efb0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2efc0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2efd0 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d  Context {H16210}
2efe0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
2eff0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2f000 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  on of aggregate 
2f010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
2f020 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2f030 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20  o allocate.** a 
2f040 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
2f050 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2f060 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
2f070 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2f080 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f090 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20  ntext() routine 
2f0a0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a  is called for a.
2f0b0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67  ** particular ag
2f0c0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20  gregate, SQLite 
2f0d0 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73  allocates nBytes
2f0e0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2f0f0 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d  es out that.** m
2f100 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2f110 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2f120 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  it. On second an
2f130 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2f140 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2f150 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2f160 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2f170 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2f180 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74  tion index,.** t
2f190 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2f1a0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20  s returned. The 
2f1b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2f1c0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2f1d0 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72  can use.** the r
2f1e0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
2f1f0 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
2f200 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  a..**.** SQLite 
2f210 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2f220 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  ees the allocate
2f230 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68  d buffer when th
2f240 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
2f250 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2f260 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2f270 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
2f280 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2f290 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2f2a0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2f2b0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2f2c0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2f2d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2f2e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  the callback rou
2f2f0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2f300 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2f310 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  te function..**.
2f320 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2f330 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2f340 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2f350 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2f360 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2f370 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2f380 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2f390 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2f3a0 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73  H16211} The firs
2f3b0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  t invocation of 
2f3c0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2f3d0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2f3e0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2f3f0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e   a particular in
2f400 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67  stance of an agg
2f410 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2f420 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61  (for a particula
2f430 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  r.**          co
2f440 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20  ntext C) causes 
2f450 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61  SQLite to alloca
2f460 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  te N bytes of me
2f470 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20  mory,.**        
2f480 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f    zero that memo
2f490 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ry, and return a
2f4a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2f4b0 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79  allocated memory
2f4c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d  ..**.** {H16213}
2f4d0 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
2f4e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2f4f0 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20  curs during.**  
2f500 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2f510 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2f520 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68  xt(C,N)] then th
2f530 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
2f540 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ns 0..**.** {H16
2f550 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20  215} Second and 
2f560 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2f570 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20  ations of.**    
2f580 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61        [sqlite3_a
2f590 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f5a0 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73  (C,N)] for the s
2f5b0 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  ame context poin
2f5c0 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20  ter C.**        
2f5d0 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70    ignore the N p
2f5e0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
2f5f0 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
2f600 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
2f610 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d        block of m
2f620 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
2f630 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f  y the first invo
2f640 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  cation..**.** {H
2f650 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72  16217} The memor
2f660 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b  y allocated by [
2f670 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f680 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2f690 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  is.**          a
2f6a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2f6b0 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63  ed on the next c
2f6c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f6d0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20  reset()].**     
2f6e0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2f6f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72  _finalize()] for
2f700 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2f710 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69  tatement] contai
2f720 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
2f730 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
2f740 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
2f750 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20  ed with context 
2f760 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  C..*/.void *sqli
2f770 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f780 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
2f790 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
2f7a0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
2f7b0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
2f7c0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  For Functions {H
2f7d0 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16240} <S20200>.
2f7e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f7f0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
2f800 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f810 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2f820 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
2f830 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
2f840 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
2f850 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
2f860 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2f870 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f880 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2f890 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f8a0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2f8b0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2f8c0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2f8d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2f8e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f8f0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
2f900 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2f910 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2f920 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2f930 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2f940 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f950 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2f960 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2f970 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2f980 7b 48 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71  {H16243} The [sq
2f990 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2f9a0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  C)] interface re
2f9b0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2f9c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f9d0 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74  P pointer from t
2f9e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f9f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2fa00 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2fa10 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2fa20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fa30 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c  ction16(D,X,N,E,
2fa40 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74  P,F,S,L)] call t
2fa50 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
2fa60 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53  registered the S
2fa70 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
2fa80 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c  ciated with [sql
2fa90 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
2faa0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2fab0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2fac0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2fad0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fae0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2faf0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2fb00 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36  s {H16250} <S606
2fb10 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  00><S20200>.**.*
2fb20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
2fb30 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2fb40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2fb50 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2fb60 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2fb70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2fb80 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2fb90 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2fba0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2fbb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2fbc0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2fbd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fbe0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2fbf0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2fc00 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2fc10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2fc20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fc30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2fc40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35  TS:.**.** {H1625
2fc50 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2fc60 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2fc70 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(C)] interface 
2fc80 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2fc90 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2fca0 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    D pointer from
2fcb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2fcc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2fcd0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2fce0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2fcf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fd00 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
2fd10 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
2fd20 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2fd30 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
2fd40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
2fd50 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73  sociated with [s
2fd60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2fd70 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  C..*/.sqlite3 *s
2fd80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2fd90 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
2fda0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2fdb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2fdc0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
2fdd0 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53  Data {H16270} <S
2fde0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
2fdf0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
2fe00 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2fe10 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
2fe20 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
2fe30 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
2fe40 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  adata with argum
2fe50 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
2fe60 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
2fe70 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
2fe80 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
2fe90 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
2fea0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
2feb0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
2fec0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
2fed0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
2fee0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
2fef0 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70  etadata may be p
2ff00 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d  reserved. This m
2ff10 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66  ay.** be used, f
2ff20 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61  or example, to a
2ff30 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  dd a regular-exp
2ff40 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
2ff50 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74   scalar.** funct
2ff60 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
2ff70 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
2ff80 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2ff90 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73  ion is stored as
2ffa0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
2ffb0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2ffc0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
2ffd0 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
2ffe0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
2fff0 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
30000 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
30010 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
30020 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
30030 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
30040 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
30050 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
30060 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
30070 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
30080 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30090 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
300a0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
300b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
300c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
300d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
300e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
300f0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
30100 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
30110 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
30120 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
30130 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
30140 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
30150 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
30160 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30170 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64  ion. If no metad
30180 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
30190 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
301a0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
301b0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
301c0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
301d0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
301e0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
301f0 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
30200 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
30210 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
30220 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
30230 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
30240 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
30250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30260 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
30270 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
30280 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
30290 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
302a0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
302b0 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
302c0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
302d0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
302e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
302f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
30300 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
30310 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
30320 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
30330 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
30340 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
30350 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
30360 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69  oyed..** If it i
30370 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
30380 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
30390 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
303a0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
303b0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
303c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
303d0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
303e0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
303f0 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
30400 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
30410 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
30420 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
30430 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
30440 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
30450 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
30460 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
30470 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
30480 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
30490 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
304a0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
304b0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
304c0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
304d0 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61    The only guara
304e0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
304f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
30500 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
30510 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
30520 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
30530 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
30540 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
30550 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
30560 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
30570 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
30580 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
30590 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
305a0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
305b0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
305c0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69  ues and SQL vari
305d0 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ables..**.** The
305e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
305f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
30600 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30610 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
30620 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30630 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
30640 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
30650 20 7b 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73   {H16272} The [s
30660 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30670 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ta(C,N)] interfa
30680 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
30690 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
306a0 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   to metadata ass
306b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
306c0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
306d0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
306e0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
306f0 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20  hose context is 
30700 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  C, or NULL if th
30710 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
30720 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ta associated.**
30730 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
30740 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  hat parameter..*
30750 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68  *.** {H16274} Th
30760 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
30770 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
30780 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67   interface assig
30790 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ns a metadata.**
307a0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
307b0 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70  r P to the Nth p
307c0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
307d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  SQL function wit
307e0 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a  h context C..**.
307f0 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69  ** {H16276} SQLi
30800 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
30810 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
30820 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
30830 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
30840 20 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20     which is the 
30850 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72  metadata pointer
30860 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63   P following a c
30870 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  all to.**       
30880 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
30890 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
308a0 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65  ] when SQLite ce
308b0 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20  ases to hold.** 
308c0 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74           the met
308d0 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  adata..**.** {H1
308e0 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61  6277} SQLite cea
308f0 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61  ses to hold meta
30900 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20  data for an SQL 
30910 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
30920 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  er.**          w
30930 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  hen the value of
30940 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
30950 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
30960 48 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71  H16278} When [sq
30970 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30980 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69  a(C,N,P,D)] is i
30990 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74  nvoked, the dest
309a0 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ructor.**       
309b0 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72     is called for
309c0 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64   any prior metad
309d0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
309e0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
309f0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
30a00 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20    context C and 
30a10 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a  parameter N..**.
30a20 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69  ** {H16279} SQLi
30a30 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73  te will call des
30a40 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79  tructors for any
30a50 20 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20   metadata it is 
30a60 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  holding.**      
30a70 20 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75      in a particu
30a80 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74  lar [prepared st
30a90 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20  atement] S when 
30aa0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
30ab0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
30ac0 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  t(S)] or [sqlite
30ad0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
30ae0 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69  s called..*/.voi
30af0 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
30b00 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
30b10 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
30b20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
30b30 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
30b40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
30b50 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
30b60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
30b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
30b80 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
30b90 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
30ba0 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31  tor Behavior {H1
30bb0 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a  0280} <S30100>.*
30bc0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
30bd0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
30be0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
30bf0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
30c00 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
30c10 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
30c20 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
30c30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
30c40 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
30c50 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
30c60 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
30c70 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
30c80 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
30c90 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
30ca0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
30cb0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
30cc0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
30cd0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
30ce0 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
30cf0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
30d00 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
30d10 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
30d20 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
30d30 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
30d40 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
30d50 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
30d60 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
30d70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
30d80 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
30d90 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
30da0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
30db0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
30dc0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
30dd0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
30de0 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
30df0 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
30e00 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
30e10 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
30e20 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
30e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
30e40 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
30e50 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
30e60 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
30e70 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
30e80 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
30e90 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
30ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30eb0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
30ec0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
30ed0 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d  unction {H16400}
30ee0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
30ef0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
30f00 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
30f10 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
30f20 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
30f30 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
30f40 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
30f50 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
30f60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30f70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
30f80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30f90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
30fa0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
30fb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
30fc0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
30fd0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
30fe0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
30ff0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
31000 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
31010 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
31020 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
31030 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
31040 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
31050 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
31060 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
31070 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
31080 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
31090 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
310a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
310b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
310c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
310d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
310e0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
310f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31100 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
31110 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
31120 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
31130 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
31140 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
31150 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
31160 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
31170 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
31180 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
31190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
311a0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
311b0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
311c0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
311d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
311e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
311f0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
31200 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
31210 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
31220 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
31230 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
31240 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31250 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
31260 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
31270 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
31280 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
31290 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
312a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
312b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
312c0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
312d0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
312e0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
312f0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
31300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31310 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
31320 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31330 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
31340 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
31350 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
31360 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
31370 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53   exception..** S
31380 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
31390 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
313a0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
313b0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
313c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
313d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
313e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
313f0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
31400 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
31410 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72  e.  SQLite inter
31420 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
31430 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
31440 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
31450 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
31460 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a   UTF-8. SQLite.*
31470 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
31480 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
31490 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
314a0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
314b0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
314c0 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65  e order.  If the
314d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
314e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
314f0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
31500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31510 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
31520 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
31530 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
31540 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
31550 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
31560 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
31570 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
31580 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
31590 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
315a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
315b0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
315c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
315d0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
315e0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
315f0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
31600 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31610 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
31620 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
31630 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
31640 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ge..** The sqlit
31650 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31660 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
31670 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
31680 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
31690 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
316a0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
316b0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
316c0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
316d0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
316e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
316f0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
31700 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
31710 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
31720 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
31730 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
31740 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
31750 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
31760 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
31770 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
31780 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
31790 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
317a0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
317b0 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a  .  By default,.*
317c0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
317d0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
317e0 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20  .  A subsequent 
317f0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
31800 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
31810 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
31820 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
31830 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
31840 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
31850 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ROR..**.** The s
31860 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
31870 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
31880 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
31890 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
318a0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
318b0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
318c0 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20  BLOB is to long 
318d0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
318e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
318f0 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
31900 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
31910 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
31920 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
31930 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
31940 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
31950 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  failed..**.** Th
31960 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31970 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
31980 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
31990 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
319a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
319b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
319c0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
319d0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
319e0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
319f0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
31a00 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
31a10 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
31a20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31a30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
31a40 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
31a50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31a60 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
31a70 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
31a80 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
31a90 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
31aa0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31ab0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
31ac0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
31ad0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31ae0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
31af0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31b00 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31b10 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
31b20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31b30 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
31b40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31b50 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
31b60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31b70 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
31b80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
31b90 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
31ba0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
31bb0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
31bc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31bd0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31be0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
31bf0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
31c00 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
31c10 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
31c20 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
31c30 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
31c40 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
31c50 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
31c60 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
31c70 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
31c80 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
31c90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
31ca0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
31cb0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
31cc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31cd0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
31ce0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
31cf0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31d10 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31d20 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
31d30 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
31d40 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
31d50 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31d60 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
31d70 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
31d80 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
31d90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
31da0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
31db0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31dc0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
31dd0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
31de0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
31df0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
31e00 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
31e10 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
31e20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
31e30 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
31e40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31e50 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
31e60 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
31e70 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
31e80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
31e90 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31ea0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
31eb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
31ec0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
31ed0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
31ee0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
31ef0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
31f00 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
31f10 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
31f20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
31f30 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
31f40 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
31f50 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
31f60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31f80 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31f90 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
31fa0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
31fb0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
31fc0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
31fd0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
31fe0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
31ff0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
32000 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
32010 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
32020 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
32030 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61  the it or call a
32040 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e   destructor when
32050 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
32060 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
32070 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
32080 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
32090 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
320a0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
320b0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
320c0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
320d0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
320e0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
320f0 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
32100 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
32110 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
32120 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
32130 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
32140 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
32150 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
32160 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
32170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32180 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
32190 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
321a0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
321b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
321c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
321d0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
321e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
321f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
32200 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
32210 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
32220 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
32230 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
32240 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
32250 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
32260 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
32270 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
32280 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
32290 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
322a0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
322b0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
322c0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
322d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
322e0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
322f0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
32300 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32310 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
32320 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
32330 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
32340 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32350 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32360 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
32370 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
32380 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
32390 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
323a0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
323b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
323c0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
323d0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
323e0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
323f0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
32400 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
32410 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
32420 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32430 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
32440 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
32450 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
32460 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
32470 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
32480 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
32490 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
324a0 48 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61  H16403} The defa
324b0 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ult return value
324c0 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75   from any SQL fu
324d0 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a  nction is NULL..
324e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54  **.** {H16406} T
324f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32500 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
32510 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32520 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32530 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32540 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32550 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74  o be a BLOB that
32560 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20   is N bytes.**  
32570 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74          in lengt
32580 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65  h and with conte
32590 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  nt pointed to by
325a0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30   V..**.** {H1640
325b0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
325c0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c  result_double(C,
325d0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
325e0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
325f0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
32600 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
32610 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74   to be the float
32620 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
32630 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32  V..**.** {H16412
32640 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32650 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c  esult_error(C,V,
32660 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
32670 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
32680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
32690 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
326a0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
326b0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
326c0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
326d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
326e0 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72  nd a UTF-8 error
326f0 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20   message copied 
32700 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
32710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
32720 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20  st zero byte or 
32730 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
32740 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
32750 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
32760 48 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c  H16415} The [sql
32770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32780 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  r16(C,V,N)] inte
32790 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
327a0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
327b0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
327c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
327d0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
327e0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
327f0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
32800 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
32810 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
32820 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73  order error mess
32830 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  age.**          
32840 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70  copied from V up
32850 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
32860 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72  ro terminator or
32870 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a   until N bytes.*
32880 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72  *          are r
32890 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
328a0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
328b0 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  418} The [sqlite
328c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
328d0 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66  oobig(C)] interf
328e0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
328f0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
32900 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
32910 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32920 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
32930 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
32940 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
32950 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e  E_TOOBIG] and an
32960 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
32970 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
32980 2a 20 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b  * {H16421} The [
32990 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
329a0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69  rror_nomem(C)] i
329b0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
329c0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
329d0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
329e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
329f0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
32a00 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
32a10 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
32a20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e  SQLITE_NOMEM] an
32a30 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
32a40 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
32a50 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54  **.** {H16424} T
32a60 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32a70 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c  lt_error_code(C,
32a80 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  E)] interface ch
32a90 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
32aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
32ab0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
32ac0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
32ad0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
32ae0 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20  or code E..**   
32af0 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72         The error
32b00 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73   message text is
32b10 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
32b20 2a 20 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b  * {H16427} The [
32b30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
32b40 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  nt(C,V)] interfa
32b50 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
32b60 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
32b70 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
32b80 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
32b90 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  32-bit integer v
32ba0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
32bb0 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  16430} The [sqli
32bc0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
32bd0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
32be0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
32bf0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
32c00 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
32c10 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34  n C to be the 64
32c20 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
32c30 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
32c40 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  433} The [sqlite
32c50 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29  3_result_null(C)
32c60 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32c70 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32c80 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32c90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32ca0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
32cb0 20 7b 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73   {H16436} The [s
32cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32cd0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  xt(C,V,N,D)] int
32ce0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32cf0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32d00 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32d10 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32d20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
32d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 75  .**          V u
32d40 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
32d50 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
32d60 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
32d70 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
32d80 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
32d90 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
32da0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20  .**.** {H16439} 
32db0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32dc0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
32dd0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
32de0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32df0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
32e00 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32e10 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
32e20 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
32e30 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
32e40 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
32e50 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
32e60 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
32e70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
32e80 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
32e90 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
32ea0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
32eb0 2a 20 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b  * {H16442} The [
32ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32ed0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
32ee0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32ef0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32f00 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32f10 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32f20 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
32f30 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
32f40 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
32f50 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
32f60 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
32f70 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
32f80 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
32f90 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e   bytes or V if N
32fa0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
32fb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d  ..**.** {H16445}
32fc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32fd0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
32fe0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
32ff0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
33000 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
33010 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
33020 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
33030 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
33040 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
33050 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74  string V up to t
33060 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
33070 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
33080 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
33090 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
330a0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
330b0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
330c0 20 7b 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73   {H16448} The [s
330d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
330e0 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  lue(C,V)] interf
330f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
33100 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
33110 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
33120 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
33130 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
33140 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
33150 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
33160 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31  V..**.** {H16451
33170 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
33180 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
33190 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
331a0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
331b0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
331c0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
331d0 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74  C to be an N-byt
331e0 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65  e BLOB of all ze
331f0 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ros..**.** {H164
33200 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  54} The [sqlite3
33210 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d  _result_error()]
33220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
33230 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a  sult_error16()].
33240 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
33250 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f  rfaces make a co
33260 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f  py of their erro
33270 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
33280 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  s before.**     
33290 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a       returning..
332a0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49  **.** {H16457} I
332b0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
332c0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
332d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
332e0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
332f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
33300 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33310 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
33320 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33330 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
33340 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
33350 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
33360 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
33370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33390 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
333a0 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20  is the constant 
333b0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a  [SQLITE_STATIC].
333c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
333d0 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69   no destructor i
333e0 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e  s ever called on
333f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61   the pointer V a
33400 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  nd SQLite.**    
33410 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68        assumes th
33420 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c  at V is immutabl
33430 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30  e..**.** {H16460
33440 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
33450 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
33460 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
33470 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
33480 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
33490 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
334a0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
334b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
334c0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
334d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
334e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
334f0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
33500 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
33510 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33520 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
33530 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
33540 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nt.**          [
33550 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
33560 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72  ] then the inter
33570 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f  faces makes a co
33580 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
33590 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66        content of
335a0 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74   V and retains t
335b0 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b  he copy..**.** {
335c0 48 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44  H16463} If the D
335d0 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
335e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
335f0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
33600 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
33610 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
33620 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
33630 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
33640 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
33650 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
33660 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
33670 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
33680 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
33690 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
336a0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
336b0 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65  ,V,N,D)] is some
336c0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
336d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
336e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
336f0 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20  ITE_STATIC] and 
33700 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
33710 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  T] then.**      
33720 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20      SQLite will 
33730 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
33740 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61  uctor D with V a
33750 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d  s its only argum
33760 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
33770 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
33780 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20  shed with the V 
33790 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73  value..*/.void s
337a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
337b0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
337c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
337d0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
337e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
337f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
33800 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
33810 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
33820 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33830 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
33840 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33850 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
33860 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33870 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
33880 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33890 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
338a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
338b0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
338c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
338d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
338e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
338f0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
33900 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
33910 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
33920 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
33930 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
33940 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33950 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
33960 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
33970 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33980 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
33990 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
339a0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
339b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
339c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
339d0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
339e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
339f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33a00 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
33a10 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33a20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33a30 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
33a40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33a50 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33a60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33a70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33a80 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
33a90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33aa0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33ab0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
33ac0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33ad0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
33ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33af0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
33b00 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
33b10 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
33b20 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
33b30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33b50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33b60 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
33b70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33b80 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
33b90 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
33ba0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
33bb0 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d  quences {H16600}
33bc0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20300>.**.** 
33bd0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
33be0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
33bf0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
33c00 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
33c10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
33c20 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
33c30 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
33c40 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
33c50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
33c60 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
33c70 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
33c80 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
33c90 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
33ca0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33cb0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
33cc0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33cd0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
33ce0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
33cf0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
33d00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33d10 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  . In all cases.*
33d20 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
33d30 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
33d40 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
33d50 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
33d60 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
33d70 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  ay be one of the
33d80 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49   constants [SQLI
33d90 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51  TE_UTF8],.** [SQ
33da0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72  LITE_UTF16LE] or
33db0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
33dc0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
33dd0 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
33de0 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
33df0 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
33e00 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
33e10 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
33e20 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
33e30 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
33e40 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
33e50 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
33e60 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
33e70 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
33e80 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
33e90 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
33ea0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
33eb0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
33ec0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
33ed0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
33ee0 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
33ef0 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d  rings.** of UTF-
33f00 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
33f10 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
33f20 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
33f30 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
33f40 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
33f50 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
33f60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
33f70 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
33f80 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69  gument.  If it i
33f90 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
33fa0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
33fb0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
33fc0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
33fd0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
33fe0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
33ff0 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20  ymore)..** Each 
34000 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
34010 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75  tion supplied fu
34020 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
34030 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a  d, it is passed.
34040 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20  ** as its first 
34050 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79  parameter a copy
34060 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
34070 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
34080 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
34090 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
340a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20  _collation() or 
340b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
340c0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
340d0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
340e0 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
340f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  he application-s
34100 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
34110 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
34120 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
34130 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74  nted by a (lengt
34140 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e  h, data) pair an
34150 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
34160 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
34170 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
34180 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
34190 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
341a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
341b0 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
341c0 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70  . {END}  The app
341d0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
341e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
341f0 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
34200 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
34210 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
34220 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
34230 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
34240 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
34250 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
34260 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
34270 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
34280 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
34290 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
342a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
342b0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
342c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
342d0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65  lation().** exce
342e0 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
342f0 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
34300 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
34310 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
34320 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
34330 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
34340 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
34350 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
34360 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
34370 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
34380 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
34390 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
343a0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
343b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
343c0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
343d0 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  ** Collations ar
343e0 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
343f0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
34400 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
34410 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f  lls to the.** co
34420 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
34430 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
34440 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  en the [database
34450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
34460 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20  closed.** using 
34470 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
34480 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
34490 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  NTS:.**.** {H166
344a0 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
344b0 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20   call to the.** 
344c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
344d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
344e0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
344f0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  D)] interface.**
34500 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
34510 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61  ers function F a
34520 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  s the comparison
34530 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74   function used t
34540 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d  o.**          im
34550 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f  plement collatio
34560 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  n X on the [data
34570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34580 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20   B for.**       
34590 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76     databases hav
345a0 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a  ing encoding E..
345b0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53  **.** {H16604} S
345c0 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64  QLite understand
345d0 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  s the X paramete
345e0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
345f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34600 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
34610 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61  X,E,P,F,D)] as a
34620 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
34630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
34640 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69  -8 string in whi
34650 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72  ch case is ignor
34660 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61  ed for ASCII cha
34670 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20  racters and.**  
34680 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69          is signi
34690 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41  ficant for non-A
346a0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e  SCII characters.
346b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20  .**.** {H16606} 
346c0 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73  Successive calls
346d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
346e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
346f0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
34700 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
34710 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
34720 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c  for B, X, and E,
34730 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
34740 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
34750 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20     of P, F, and 
34760 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39  D..**.** {H16609
34770 7d 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63  } If the destruc
34780 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65  tor D in [sqlite
34790 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
347a0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
347b0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
347c0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
347d0 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69   it is called wi
347e0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
347f0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
34800 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e     collating fun
34810 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
34820 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
34830 2a 20 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c  * {H16612} A col
34840 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34850 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
34860 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64  it is overloaded
34870 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d  ..**.** {H16615}
34880 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
34890 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
348a0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
348b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
348c0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f            is clo
348d0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
348e0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
348f0 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20  ** {H16618} The 
34900 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71  pointer P in [sq
34910 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34920 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
34930 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
34940 20 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68      is passed th
34950 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
34960 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
34970 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a  the comparison.*
34980 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
34990 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75  ion F for all su
349a0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
349b0 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a  ions of F..**.**
349c0 20 7b 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c   {H16621} A call
349d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
349e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
349f0 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61  X,E,P,F)] is exa
34a00 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctly.**         
34a10 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63   the same as a c
34a20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34a30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34a40 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20  _v2()] with.**  
34a50 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
34a60 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
34a70 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f  a NULL destructo
34a80 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34  r..**.** {H16624
34a90 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73  } Following a [s
34aa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34ab0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
34ac0 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,P,F,D)],.**    
34ad0 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65        SQLite use
34ae0 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  s the comparison
34af0 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
34b00 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69  all text compari
34b10 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
34b20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
34b30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34b40 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78  ection] B on tex
34b50 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a  t values that.**
34b60 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68            use th
34b70 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75  e collating sequ
34b80 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a  ence named X..**
34b90 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65  .** {H16627} The
34ba0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34bb0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58  _collation16(B,X
34bc0 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74  ,E,P,F)] works t
34bd0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
34be0 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f      as [sqlite3_
34bf0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34c00 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63  (B,X,E,P,F)] exc
34c10 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ept that the.** 
34c20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
34c30 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64  on name X is und
34c40 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31  erstood as UTF-1
34c50 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
34c60 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
34c70 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54     instead of UT
34c80 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  F-8..**.** {H166
34c90 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  30} When multipl
34ca0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
34cb0 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ctions are avail
34cc0 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d  able for the sam
34cd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
34ce0 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
34cf0 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73  , SQLite chooses
34d00 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74   the one whose t
34d10 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
34d20 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65           require
34d30 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
34d40 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  nt of conversion
34d50 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c   from the defaul
34d60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  t.**          te
34d70 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  xt encoding of t
34d80 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
34d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34da0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
34db0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
34dc0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
34dd0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
34de0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
34df0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
34e00 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34e10 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34e20 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34e30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34e40 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
34e50 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
34e60 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
34e70 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
34e80 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
34e90 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
34ea0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
34eb0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
34ec0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
34ed0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
34ee0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34ef0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
34f00 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
34f10 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
34f20 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
34f30 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
34f40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
34f50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
34f60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
34f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f80 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
34f90 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36  d Callbacks {H16
34fa0 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  700} <S20300>.**
34fb0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
34fc0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
34fd0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
34fe0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
34ff0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
35000 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
35010 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
35020 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
35030 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
35040 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
35050 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63  nection] to be c
35060 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
35070 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
35080 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
35090 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
350a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
350b0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
350c0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
350d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
350e0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
350f0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
35100 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
35110 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
35120 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
35130 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
35140 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31  ed in UTF-8. {H1
35150 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
35160 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35170 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
35180 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
35190 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
351a0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
351b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
351c0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  * A call to eith
351d0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
351e0 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
351f0 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
35200 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
35210 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
35220 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35230 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
35240 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
35250 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
35260 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
35270 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
35280 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
35290 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
352a0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
352b0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
352c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
352d0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
352e0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
352f0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
35300 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
35310 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
35320 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
35330 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
35340 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
35350 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
35360 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
35370 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
35380 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
35390 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
353a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
353b0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
353c0 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
353d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
353e0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
353f0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
35400 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
35410 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
35420 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
35430 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35440 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
35450 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
35460 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35470 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
35480 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
35490 48 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73  H16702} A succes
354a0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
354b0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
354c0 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a  needed(D,P,F)].*
354d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
354e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
354f0 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29  _needed16(D,P,F)
35500 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20  ] causes.**     
35510 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
35520 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
35530 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62   to invoke callb
35540 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74  ack F with first
35550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
35560 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
35570 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d  r it needs a com
35580 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
35590 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20   for a.**       
355a0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
355b0 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f  uence that it do
355c0 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75  es not know abou
355d0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34  t..**.** {H16704
355e0 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75  } Each successfu
355f0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
35600 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35610 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ded()] or.**    
35620 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
35630 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
35640 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  6()] overrides t
35650 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69  he callback regi
35660 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
35670 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
35680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35690 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61  ion] by prior ca
356a0 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  lls to either.**
356b0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
356c0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37  ace..**.** {H167
356d0 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  06} The name of 
356e0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f  the requested co
356f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35700 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a   passed in the.*
35710 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70  *          4th p
35720 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35730 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55  callback is in U
35740 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c  TF-8 if the call
35750 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
35760 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20   was registered 
35770 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
35780 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
35790 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
357a0 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20     is in UTF-16 
357b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
357c0 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r if the callbac
357d0 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  k was.**        
357e0 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69    registered usi
357f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
35800 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
35810 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
35820 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35830 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
35840 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
35850 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
35860 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
35870 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
35880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
35890 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
358a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
358b0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
358c0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
358d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
358e0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
358f0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
35900 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
35910 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
35920 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
35930 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
35940 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
35950 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
35960 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
35970 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
35980 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
35990 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
359a0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
359b0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
359c0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
359d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
359e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
359f0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
35a00 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
35a10 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
35a20 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
35a30 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
35a40 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
35a50 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
35a60 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
35a70 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
35a80 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
35a90 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
35aa0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
35ab0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
35ac0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
35ad0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
35ae0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
35af0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
35b00 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
35b10 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
35b20 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
35b30 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
35b40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35b50 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
35b60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
35b70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
35b80 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
35b90 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
35ba0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
35bb0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
35bc0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
35bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
35be0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
35bf0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
35c00 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30  {H10530} <S40410
35c10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
35c20 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
35c30 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
35c40 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
35c50 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
35c60 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
35c70 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
35c80 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
35c90 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
35ca0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
35cb0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
35cc0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
35cd0 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
35ce0 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
35cf0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
35d00 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
35d10 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
35d20 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
35d30 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
35d40 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
35d50 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
35d60 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
35d70 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
35d80 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
35d90 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
35da0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51  turned..**.** SQ
35db0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
35dc0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
35dd0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
35de0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
35df0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
35e00 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
35e10 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ject..**.** INVA
35e20 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
35e30 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  10533} The [sqli
35e40 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e  te3_sleep(M)] in
35e50 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20  terface invokes 
35e60 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20  the xSleep.**   
35e70 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66         method of
35e80 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
35e90 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69  lite3_vfs|VFS] i
35ea0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20  n order to.**   
35eb0 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65         suspend e
35ec0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
35ed0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66  current thread f
35ee0 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20  or at least.**  
35ef0 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73          M millis
35f00 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  econds..**.** {H
35f10 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  10536} The [sqli
35f20 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e  te3_sleep(M)] in
35f30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35f40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
35f50 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73            millis
35f60 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
35f70 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74  actually request
35f80 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74  ed of the operat
35f90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
35fa0 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69  system, which mi
35fb0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
35fc0 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  an the parameter
35fd0 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   M..*/.int sqlit
35fe0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
35ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36000 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
36010 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
36020 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33  rary Files {H103
36030 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  10} <S20000>.**.
36040 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
36050 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
36060 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
36070 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
36080 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
36090 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
360a0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
360b0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
360c0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
360d0 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   by SQLite will 
360e0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
360f0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66  t directory.  If
36100 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
36110 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
36120 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
36130 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
36140 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
36150 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
36160 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
36170 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
36180 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66  ot safe to modif
36190 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
361a0 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73 65  once a [database
361b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
361c0 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  has been opened.
361d0 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64    It is intended
361e0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
361f0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
36200 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
36210 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
36220 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
36230 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
36240 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
36250 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20   have been call 
36260 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  and remain uncha
36270 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e  nged thereafter.
36280 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
36290 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
362a0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
362b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
362c0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
362d0 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39  ommit Mode {H129
362e0 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20  30} <S60200>.** 
362f0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
36300 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
36310 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
36320 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
36330 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36340 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
36350 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
36360 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
36370 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
36380 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
36390 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
363a0 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d  tively.  Autocom
363b0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
363c0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75  y default..** Au
363d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
363e0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
363f0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
36400 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
36410 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
36420 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
36430 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
36440 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
36450 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
36460 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
36470 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
36480 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
36490 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
364a0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
364b0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
364c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
364d0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
364e0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
364f0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
36500 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
36510 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
36520 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
36530 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
36540 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
36550 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
36560 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
36570 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
36580 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
36590 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
365a0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
365b0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
365c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
365d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
365e0 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
365f0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
36600 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  it(D)] interface
36610 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
36620 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  o or.**         
36630 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61   zero if the [da
36640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36650 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f  n] D is or is no
36660 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  t in autocommit.
36670 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65  **          mode
36680 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
36690 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41  **.** {H12932} A
366a0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
366b0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
366c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20  .**.** {H12933} 
366d0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
366e0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
366f0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47   successful [BEG
36700 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
36710 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41 75  *.** {H12934} Au
36720 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
36730 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75   enabled by a su
36740 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54  ccessful [COMMIT
36750 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a  ] or [ROLLBACK].
36760 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74  **          stat
36770 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  ement..**.** ASS
36780 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
36790 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {A12936} If anot
367a0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
367b0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
367c0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
367d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
367e0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
367f0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
36800 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
36810 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
36820 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
36830 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36840 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
36850 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
36860 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
36870 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
36880 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
36890 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
368a0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32  Statement {H1312
368b0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S60600>.**.*
368c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
368d0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
368e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
368f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36900 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
36910 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
36920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
36930 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61  longs.  The data
36940 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
36950 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74  rned by.** sqlit
36960 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
36970 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
36980 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
36990 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
369a0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
369b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
369c0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
369d0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
369e0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
369f0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
36a00 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
36a10 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  st place..**.** 
36a20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
36a30 2a 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b  * {H13123} The [
36a40 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
36a50 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
36a60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36a70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
36a80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36a90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
36aa0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a  iated with the.*
36ab0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
36ac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36ad0 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  S..*/.sqlite3 *s
36ae0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
36af0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
36b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36b10 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
36b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36b30 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30  nt {H13140} <S60
36b40 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
36b50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36b60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36b70 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
36b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
36b90 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
36ba0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
36bb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36bc0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
36bd0 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
36be0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
36bf0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
36c00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
36c10 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
36c20 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
36c30 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
36c40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36c50 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65   pDb.  If no pre
36c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
36c70 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
36c80 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
36c90 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
36ca0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
36cb0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
36cc0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49  **.** {H13143} I
36cd0 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
36ce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
36cf0 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72  hat holds one or
36d00 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
36d10 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70    unfinalized [p
36d20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36d30 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e  ts] and S is a N
36d40 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20  ULL pointer,.** 
36d50 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
36d60 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
36d70 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20  (D, S)] routine 
36d80 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70  shall return a p
36d90 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
36da0 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65     to one of the
36db0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36dc0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
36dd0 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  with D..**.** {H
36de0 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61  13146} If D is a
36df0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36e00 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
36e10 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64  s no unfinalized
36e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
36e30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36e40 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55  s] and S is a NU
36e50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
36e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
36e70 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
36e80 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
36e90 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55  hall return a NU
36ea0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
36eb0 2a 20 7b 48 31 33 31 34 39 7d 20 49 66 20 53 20  * {H13149} If S 
36ec0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
36ed0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65  tatement] in the
36ee0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36ef0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
36f00 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f       and S is no
36f10 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61  t the last prepa
36f20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  red statement in
36f30 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   D, then.**     
36f40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
36f50 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
36f60 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
36f70 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  urn a pointer.**
36f80 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
36f90 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
36fa0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66  tatement in D af
36fb0 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ter S..**.** {H1
36fc0 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68  3152} If S is th
36fd0 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64  e last [prepared
36fe0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74   statement] in t
36ff0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
37000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37010 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20  ion] D then the 
37020 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
37030 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20  mt(D, S)].**    
37040 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
37050 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  all return a NUL
37060 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
37070 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
37080 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 68 65  .** {A13154} The
37090 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
370a0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
370b0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
370c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
370d0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
370e0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
370f0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
37100 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
37110 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
37120 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
37130 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
37140 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
37150 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
37160 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
37170 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
37180 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
37190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
371a0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
371b0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
371c0 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35  Callbacks {H1295
371d0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
371e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
371f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
37200 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
37210 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
37220 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
37230 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
37240 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
37250 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
37260 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
37270 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
37280 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
37290 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
372a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
372b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
372c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
372d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
372e0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
372f0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
37300 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
37310 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
37320 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
37330 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
37340 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
37350 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
37360 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
37370 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
37380 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
37390 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
373a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
373b0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
373c0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
373d0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
373e0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
373f0 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ack..** If the c
37400 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
37410 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
37420 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
37430 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
37440 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
37450 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
37460 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
37470 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
37480 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
37490 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a  gistered, its.**
374a0 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
374b0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
374c0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
374d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69  rned..**.** Regi
374e0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
374f0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
37500 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
37510 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72  *.** For the pur
37520 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
37530 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
37540 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
37550 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
37560 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
37570 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
37580 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
37590 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
375a0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
375b0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
375c0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
375d0 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20  o occur..** The 
375e0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
375f0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
37600 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
37610 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
37620 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
37630 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
37640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37650 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  n is closed..** 
37660 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
37670 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
37680 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
37690 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c  ction is.** roll
376a0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
376b0 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  a commit callbac
376c0 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a  k returned non-z
376d0 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43  ero..** <todo> C
376e0 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74  heck on this </t
376f0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  odo>.**.** INVAR
37700 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
37710 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2951} The [sqlit
37720 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
37730 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
37740 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
37750 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
37760 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
37770 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
37780 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
37790 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
377a0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
377b0 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b  commits on the [
377c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
377d0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
377e0 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69  12952} The [sqli
377f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
37800 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
37810 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  e returns the P 
37820 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  argument.**     
37830 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72       from the pr
37840 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68  evious call with
37850 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37870 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  D,.**          o
37880 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
37890 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70  rst call for a p
378a0 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
378b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
378c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20  .**.** {H12953} 
378d0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
378e0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
378f0 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  k()] overwrites 
37900 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
37910 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
37920 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c  red by prior cal
37930 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35  ls..**.** {H1295
37940 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75  4} If the F argu
37950 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
37960 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
37970 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  ,P)] is NULL.** 
37980 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
37990 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
379a0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
379b0 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61  ed and no callba
379c0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
379d0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
379e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
379f0 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  mits..**.** {H12
37a00 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d  955} If the comm
37a10 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
37a20 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65  rns non-zero the
37a30 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a  n the commit is.
37a40 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76  **          conv
37a50 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
37a60 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lback..**.** {H1
37a70 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2961} The [sqlit
37a80 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37a90 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
37aa0 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65  ce registers the
37ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
37ac0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46  lback function F
37ad0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37ae0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
37af0 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20  henever.**      
37b00 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f      a transactio
37b10 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20  n rolls back on 
37b20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37b30 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
37b40 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20  ** {H12962} The 
37b50 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
37b60 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
37b70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37b80 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20   the P.**       
37b90 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d     argument from
37ba0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
37bb0 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ll with the same
37bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
37bd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37be0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e  n] D, or NULL on
37bf0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a   the first call.
37c00 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
37c10 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
37c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37c30 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36   D..**.** {H1296
37c40 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
37c50 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
37c60 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  k_hook()] overwr
37c70 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
37c80 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  k.**          re
37c90 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f  gistered by prio
37ca0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  r calls..**.** {
37cb0 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46  H12964} If the F
37cc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
37cd0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37ce0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e  ook(D,F,P)] is N
37cf0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
37d00 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63  then the rollbac
37d10 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  k hook callback 
37d20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20  is canceled and 
37d30 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
37d40 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
37d50 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
37d60 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
37d70 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
37d80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
37d90 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
37da0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
37db0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
37dc0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
37dd0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
37de0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
37df0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37e00 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
37e10 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
37e20 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30  ks {H12970} <S60
37e30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  400>.**.** The s
37e40 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37e50 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
37e60 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
37e70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
37e80 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
37e90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
37ea0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
37eb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
37ec0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
37ed0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
37ee0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
37ef0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
37f00 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
37f10 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37f20 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
37f30 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
37f40 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37f50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37f60 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
37f70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
37f80 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
37f90 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
37fa0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
37fb0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
37fc0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
37fd0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54  or deleted..** T
37fe0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37ff0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
38000 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
38010 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
38020 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
38030 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
38040 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c  * The second cal
38050 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
38060 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
38070 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
38080 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
38090 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
380a0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
380b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
380c0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
380d0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
380e0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74  nvoked..** The t
380f0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
38100 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
38110 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
38120 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
38130 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** database an
38140 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  d table name con
38150 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
38160 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65  cted row..** The
38170 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
38180 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
38190 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
381a0 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  w. In the case o
381b0 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c 20  f.** an update, 
381c0 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69  this is the rowi
381d0 64 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  d after the upda
381e0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
381f0 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
38200 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
38210 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
38220 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
38230 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
38240 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
38250 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
38260 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  sequence)..**.**
38270 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
38280 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
38290 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
382a0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
382b0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
382c0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
382d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
382e0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
382f0 0a 2a 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65  .** {H12971} The
38300 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
38310 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
38320 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
38330 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
38340 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
38350 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
38360 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61   with first para
38370 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72  meter P whenever
38380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
38390 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69  able row is modi
383a0 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20  fied, inserted, 
383b0 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a  or deleted on.**
383c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
383d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
383e0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
383f0 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2973} The [sqlit
38400 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
38410 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
38420 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
38430 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ue.**          o
38440 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76  f P for the prev
38450 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65  ious call on the
38460 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
38470 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a  connection] D,.*
38480 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
38490 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  LL for the first
384a0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
384b0 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64  2975} If the upd
384c0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
384d0 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  k F in [sqlite3_
384e0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
384f0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  P)].**          
38500 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
38510 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62   no update callb
38520 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a  acks are made..*
38530 2a 0a 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61  *.** {H12977} Ea
38540 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
38550 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
38560 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65  D,F,P)] override
38570 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a  s prior calls.**
38580 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
38590 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20   same interface 
385a0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
385b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
385c0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
385d0 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68  79} The update h
385e0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
385f0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
38600 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
38610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62  .**          tab
38620 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69  les such as sqli
38630 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
38640 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72  lite_sequence ar
38650 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  e modified..**.*
38660 2a 20 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73  * {H12981} The s
38670 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
38680 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61  to the update ca
38690 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
386a0 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51     is one of [SQ
386b0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
386c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
386d0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
386e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  ,.**          de
386f0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
38700 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
38710 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
38720 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
38730 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20  .**.** {H12983} 
38740 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
38750 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
38760 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
38770 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a  ontain pointers.
38780 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a  **          to z
38790 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
387a0 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69  TF-8 strings whi
387b0 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73  ch are the names
387c0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
387d0 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64      database and
387e0 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62   table that is b
387f0 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a  eing updated...*
38800 2a 20 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66  * {H12985} The f
38810 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
38820 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72  rameter is the r
38830 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20  owid of the row 
38840 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  after.**        
38850 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63    the change occ
38860 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  urs..*/.void *sq
38870 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
38880 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
38890 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
388a0 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
388b0 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
388c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
388d0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
388e0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
388f0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or D