/ Hex Artifact Content
Login

Artifact 8a00ed8707a16ee724e9e500b07e9af3a6fcc9be:


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 36 35 20 32 30 30 38 2f 30  n,v 1.365 2008/0
05f0: 37 2f 30 39 20 31 33 3a 32 38 3a 35 34 20 64 72  7/09 13:28:54 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 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 46 31 30 30 31 30 7d 0a  umbers {F10010}.
0840: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
0850: 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c  _VERSION and SQL
0860: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0870: 45 52 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a  ER #defines in.*
0880: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20  * the sqlite3.h 
0890: 66 69 6c 65 20 73 70 65 63 69 66 79 20 74 68 65  file specify the
08a0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
08b0: 74 65 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a  te with which.**
08c0: 20 74 68 61 74 20 68 65 61 64 65 72 20 66 69 6c   that header fil
08d0: 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e  e is associated.
08e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73  .**.** The "vers
08f0: 69 6f 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69  ion" of SQLite i
0900: 73 20 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68  s a string of th
0910: 65 20 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a  e form "X.Y.Z"..
0920: 2a 2a 20 54 68 65 20 70 68 72 61 73 65 20 22 61  ** The phrase "a
0930: 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 20  lpha" or "beta" 
0940: 6d 69 67 68 74 20 62 65 20 61 70 70 65 6e 64 65  might be appende
0950: 64 20 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a  d after the Z..*
0960: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73  * The X value is
0970: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0980: 75 6d 62 65 72 20 61 6c 77 61 79 73 20 33 20 69  umber always 3 i
0990: 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68  n SQLite3..** Th
09a0: 65 20 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63  e X value only c
09b0: 68 61 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b  hanges when back
09c0: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
09d0: 69 74 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e  ity is.** broken
09e0: 20 61 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74   and we intend t
09f0: 6f 20 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61  o never break ba
0a00: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
0a10: 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20  ility..** The Y 
0a20: 76 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e  value is the min
0a30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0a40: 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67  r and only chang
0a50: 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65  es when.** there
0a60: 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75   are major featu
0a70: 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20  re enhancements 
0a80: 74 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64  that are forward
0a90: 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20  s compatible.** 
0aa0: 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64  but not backward
0ab0: 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a  s compatible..**
0ac0: 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20   The Z value is 
0ad0: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
0ae0: 65 72 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d  er and is increm
0af0: 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61  ented with.** ea
0b00: 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72  ch release but r
0b10: 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20  esets back to 0 
0b20: 77 68 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e  whenever Y is in
0b30: 63 72 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  cremented..**.**
0b40: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
0b50: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
0b60: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c  ] and [sqlite3_l
0b70: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0b80: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
0b90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
0ba0: 30 30 31 31 7d 20 54 68 65 20 53 51 4c 49 54 45  0011} The SQLITE
0bb0: 5f 56 45 52 53 49 4f 4e 20 23 64 65 66 69 6e 65  _VERSION #define
0bc0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e   in the sqlite3.
0bd0: 68 20 68 65 61 64 65 72 20 66 69 6c 65 20 73 68  h header file sh
0be0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
0bf0: 65 76 61 6c 75 61 74 65 20 74 6f 20 61 20 73 74  evaluate to a st
0c00: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61  ring literal tha
0c10: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20  t is the SQLite 
0c20: 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  version.**      
0c30: 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 74      with which t
0c40: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 69  he header file i
0c50: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a  s associated..**
0c60: 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 65  .** {F10014} The
0c70: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0c80: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 73  NUMBER #define s
0c90: 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f 20  hall resolve to 
0ca0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
0cb0: 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20         with the 
0cc0: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30  value (X*1000000
0cd0: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77   + Y*1000 + Z) w
0ce0: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a  here X, Y, and Z
0cf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
0d00: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0d10: 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  on, minor versio
0d20: 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20 6e  n, and release n
0d30: 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e  umber..*/.#defin
0d40: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0d50: 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53           "--VERS
0d60: 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  --".#define SQLI
0d70: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0d80: 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  R  --VERSION-NUM
0d90: 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  BER--../*.** CAP
0da0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
0db0: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
0dc0: 4e 75 6d 62 65 72 73 20 7b 46 31 30 30 32 30 7d  Numbers {F10020}
0dd0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
0de0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a  lite3_version.**
0df0: 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72  .** These featur
0e00: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
0e10: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
0e20: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
0e30: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b  ERSION].** and [
0e40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0e50: 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20  UMBER] #defines 
0e60: 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62  in the header, b
0e70: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
0e80: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69  d.** with the li
0e90: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
0ea0: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
0eb0: 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67  .  Cautious prog
0ec0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a  rammers might.**
0ed0: 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b   include a check
0ee0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
0ef0: 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20  ation to verify 
0f00: 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  that.** sqlite3_
0f10: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f20: 72 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72  r() always retur
0f30: 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  ns the value.** 
0f40: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
0f50: 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NUMBER]..**.** T
0f60: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
0f70: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
0f80: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d   returns the sam
0f90: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
0fa0: 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71   is.** in the sq
0fb0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
0fc0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e  string constant.
0fd0: 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69    The function i
0fe0: 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  s provided.** fo
0ff0: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1000: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
1010: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
1020: 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  e direct access 
1030: 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e  to string.** con
1040: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
1050: 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  e DLL..**.** INV
1060: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1070: 46 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c  F10021} The [sql
1080: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1090: 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66  number()] interf
10a0: 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ace shall return
10b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
10c0: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
10d0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
10e0: 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  _NUMBER]..**.** 
10f0: 7b 46 31 30 30 32 32 7d 20 54 68 65 20 5b 73 71  {F10022} The [sq
1100: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73  lite3_version] s
1110: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 73  tring constant s
1120: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20  hall contain.** 
1130: 20 20 20 20 20 20 20 20 20 74 68 65 20 74 65 78           the tex
1140: 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  t of the [SQLITE
1150: 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67  _VERSION] string
1160: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 33 7d  ..**.** {F10023}
1170: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   The [sqlite3_li
1180: 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e 63  bversion()] func
1190: 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
11a0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  n.**          a 
11b0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
11c0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d  sqlite3_version]
11d0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
11e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
11f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1200: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1210: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1220: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1230: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1240: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1250: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1260: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
1270: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20  t To See If The 
1280: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61  Library Is Threa
1290: 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d 0a 2a  dsafe {F10100}.*
12a0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
12b0: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
12c0: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
12d0: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
12e0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12f0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
1300: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
1310: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
1320: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1330: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1340: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1350: 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a  macro is false,.
1360: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1370: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1380: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1390: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
13a0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
13b0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
13c0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
13d0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
13e0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
13f0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1400: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1410: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1420: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1430: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1440: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1450: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1460: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1470: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1480: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1490: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
14a0: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
14b0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
14c0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
14d0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
14e0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
14f0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
1500: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
1510: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1520: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1530: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1540: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1550: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1560: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1570: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1580: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1590: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
15a0: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
15b0: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
15c0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
15d0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
15e0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15f0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
1600: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1610: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1620: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1630: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1640: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1650: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1660: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1670: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1680: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1690: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
16a0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
16b0: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
16c0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
16d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
16e0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
16f0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
1700: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
1710: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1720: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1730: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1740: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1750: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1760: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1770: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1780: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1790: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
17a0: 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65 20  ** {F10101} The 
17b0: 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
17c0: 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  afe()] function 
17d0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e  shall return non
17e0: 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20  zero if.**      
17f0: 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 20 63      SQLite was c
1800: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1810: 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e 61   its mutexes ena
1820: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 0a  bled by default.
1830: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 7a  **          or z
1840: 65 72 6f 20 69 66 20 53 51 4c 69 74 65 20 77 61  ero if SQLite wa
1850: 73 20 63 6f 6d 70 69 6c 65 64 20 73 75 63 68 20  s compiled such 
1860: 74 68 61 74 20 6d 75 74 65 78 65 73 20 61 72 65  that mutexes are
1870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72  .**          per
1880: 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61 62 6c 65  manently disable
1890: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 32  d..**.** {F10102
18a0: 7d 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  } The value retu
18b0: 72 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  rned by the [sql
18c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
18d0: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  )] function.**  
18e0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f          shall no
18f0: 74 20 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75  t change when mu
1900: 74 65 78 20 73 65 74 74 69 6e 67 20 61 72 65 20  tex setting are 
1910: 6d 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20  modified at.**  
1920: 20 20 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20          runtime 
1930: 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
1940: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
1950: 65 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20  erface and .**  
1960: 20 20 20 20 20 20 20 20 65 73 70 65 63 69 61 6c          especial
1970: 6c 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ly the [SQLITE_C
1980: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1990: 41 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AD],.**         
19a0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19b0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53  MULTITHREAD], [S
19c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
19d0: 49 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20  IALIZED],.**    
19e0: 20 20 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54        and [SQLIT
19f0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
1a00: 76 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  verbs..*/.int sq
1a10: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1a20: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1a30: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
1a40: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
1a50: 64 6c 65 20 7b 46 31 32 30 30 30 7d 0a 2a 2a 20  dle {F12000}.** 
1a60: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
1a70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
1a80: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
1a90: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
1aa0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
1ab0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
1ac0: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
1ad0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
1ae0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
1af0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
1b00: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
1b10: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
1b20: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
1b30: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
1b40: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
1b50: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1b60: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1b70: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
1b80: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b90: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
1ba0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
1bb0: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
1bc0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69  close()].** is i
1bd0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20  ts destructor.  
1be0: 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f  There are many o
1bf0: 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  ther interfaces 
1c00: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
1c10: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c20: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
1c30: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
1c40: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1c50: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c60: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
1c70: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
1c80: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
1c90: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
1ca0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1cb0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
1cc0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
1ce0: 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d 0a   Types {F10200}.
1cf0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1d00: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1d10: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1d20: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1d30: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1d40: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1d50: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1d60: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1d70: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1d80: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1d90: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1da0: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1db0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1dc0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1dd0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1de0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1df0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1e00: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
1e10: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
1e20: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
1e30: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1e40: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
1e50: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
1e60: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1e70: 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {F10201} The [sq
1e80: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
1e90: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
1ea0: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
1eb0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1ec0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
1ed0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
1ee0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
1ef0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
1f00: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
1f10: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
1f20: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1f30: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1f40: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
1f50: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1f60: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
1f70: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1f80: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
1f90: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1fa0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
1fb0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
1fc0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
1fd0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
1fe0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
1ff0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2000: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2010: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2020: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2030: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2040: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2050: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2060: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2070: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2080: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2090: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
20a0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
20b0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
20c0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
20d0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
20e0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
20f0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2100: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2110: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2120: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2130: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2140: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2150: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2160: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2170: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2180: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2190: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
21a0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
21b0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
21c0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
21d0: 63 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a  ction {F12010}.*
21e0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
21f0: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
2200: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
2210: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2220: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2230: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2240: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2250: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2260: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
2270: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2280: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2290: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
22a0: 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65  ndles] associate
22b0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73  d with.** the [s
22c0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
22d0: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
22e0: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
22f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b  object..** The [
2300: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2310: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  t()] interface c
2320: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f  an be used to lo
2330: 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65  cate all.** [pre
2340: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2350: 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
2360: 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
2370: 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73  nnection] if des
2380: 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c  ired..** Typical
2390: 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b   code might look
23a0: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
23b0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
23c0: 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  re>.** sqlite3_s
23d0: 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77  tmt *pStmt;.** w
23e0: 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73  hile( (pStmt = s
23f0: 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2400: 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a  (db, 0))!=0 ){.*
2410: 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74  * &nbsp;   sqlit
2420: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d  e3_finalize(pStm
2430: 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72  t);.** }.** </pr
2440: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
2450: 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  **.** If [sqlite
2460: 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e  3_close()] is in
2470: 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72  voked while a tr
2480: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
2490: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
24a0: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
24b0: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
24c0: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ck..**.** INVARI
24d0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
24e0: 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  011} A successfu
24f0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2500: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61  e3_close(C)] sha
2510: 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  ll destroy the.*
2520: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
2530: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2540: 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a   object C..**.**
2550: 20 7b 46 31 32 30 31 32 7d 20 41 20 73 75 63 63   {F12012} A succ
2560: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2570: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2580: 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53  ] shall return S
2590: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
25a0: 7b 46 31 32 30 31 33 7d 20 41 20 73 75 63 63 65  {F12013} A succe
25b0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
25c0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
25d0: 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61   shall release a
25e0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
25f0: 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d  emory and system
2600: 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63   resources assoc
2610: 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74 61  iated with [data
2620: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2630: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a  .**          C..
2640: 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34 7d 20 41  **.** {F12014} A
2650: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2660: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61  3_close(C)] on a
2670: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2680: 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a  ction] C that.**
2690: 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e            has on
26a0: 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b  e or more open [
26b0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26c0: 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20  nts] shall fail 
26d0: 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
26e0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
26f0: 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a  ] error code..**
2700: 0a 2a 2a 20 7b 46 31 32 30 31 35 7d 20 41 20 63  .** {F12015} A c
2710: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2720: 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20  close(C)] where 
2730: 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  C is a NULL poin
2740: 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ter shall.**    
2750: 20 20 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c        return SQL
2760: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ITE_OK..**.** {F
2770: 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c  12019} When [sql
2780: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69  ite3_close(C)] i
2790: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b  s invoked on a [
27a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27b0: 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20  ion] C.**       
27c0: 20 20 20 74 68 61 74 20 68 61 73 20 61 20 70 65     that has a pe
27d0: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
27e0: 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  n, the transacti
27f0: 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20  on shall be.**  
2800: 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62          rolled b
2810: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ack..**.** LIMIT
2820: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  ATIONS:.**.** {A
2830: 31 32 30 31 36 7d 20 54 68 65 20 43 20 70 61 72  12016} The C par
2840: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2850: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73  e3_close(C)] mus
2860: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
2870: 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  LL.**          p
2880: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
2890: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
28a0: 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
28b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
28c0: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
28d0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
28e0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
28f0: 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2900: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2910: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2920: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2930: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2940: 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b  lose(sqlite3 *);
2950: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
2960: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
2970: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
2980: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
2990: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
29a0: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
29b0: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
29c0: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
29d0: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
29e0: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
29f0: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
2a00: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
2a10: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
2a20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a30: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
2a40: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
2a50: 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a 2a  face {F12100}.**
2a60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a70: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2a80: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74   is a convenient
2a90: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20   way of running 
2aa0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53  one or more.** S
2ab0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69  QL statements wi
2ac0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
2ad0: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43  write a lot of C
2ae0: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d   code.  The UTF-
2af0: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c  8 encoded.** SQL
2b00: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2b10: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2b20: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2b30: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
2b40: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74  c()..** The stat
2b50: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2b60: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20  ated one by one 
2b70: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2b80: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69  error or.** an i
2b90: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f  nterrupt is enco
2ba0: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69  untered, or unti
2bb0: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64  l they are all d
2bc0: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61  one.  The 3rd pa
2bd0: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e  rameter.** is an
2be0: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61   optional callba
2bf0: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ck that is invok
2c00: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2c10: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72   row of any quer
2c20: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f  y.** results pro
2c30: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c  duced by the SQL
2c40: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
2c50: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2c60: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74  tells where.** t
2c70: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f  o write any erro
2c80: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a  r messages..**.*
2c90: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * The error mess
2ca0: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20  age passed back 
2cb0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2cc0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c  parameter is hel
2cd0: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  d.** in memory o
2ce0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2cf0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
2d00: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d    To avoid a mem
2d10: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65  ory leak,.** the
2d20: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61   calling applica
2d30: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c  tion should call
2d40: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2d50: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a  ] on any error.*
2d60: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  * message return
2d70: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
2d80: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65  th parameter whe
2d90: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
2da0: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65  d using.** the e
2db0: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2dc0: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2dd0: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
2de0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  2nd parameter is
2df0: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
2e00: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61  y string.** or a
2e10: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2e20: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ng only whitespa
2e30: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c  ce and comments,
2e40: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20   then no SQL.** 
2e50: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2e60: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
2e70: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
2e80: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
2e90: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2ea0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2eb0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74  implemented in t
2ec0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  erms of.** [sqli
2ed0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ee0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
2ef0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2f00: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
2f10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2f20: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  ec() routine doe
2f30: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65  s nothing to the
2f40: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63   database that c
2f50: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a  annot be done.**
2f60: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2f70: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2f80: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2f90: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2fa0: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ize()]..**.** IN
2fb0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2fc0: 7b 46 31 32 31 30 31 7d 20 41 20 73 75 63 63 65  {F12101} A succe
2fd0: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
2fe0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
2ff0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a  c(D,S,C,A,E)].**
3000: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
3010: 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61  sequentially eva
3020: 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65  luate all of the
3030: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
3040: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d 69  **          semi
3050: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
3060: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
3070: 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
3080: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
3090: 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69    string S withi
30a0: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
30b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
30d0: 0a 2a 2a 20 7b 46 31 32 31 30 32 7d 20 49 66 20  .** {F12102} If 
30e0: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
30f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3100: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20  (D,S,C,A,E)] is 
3110: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3120: 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e        the action
3130: 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61  s of the interfa
3140: 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20  ce shall be the 
3150: 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a  same as if the.*
3160: 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72  *          S par
3170: 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 65  ameter were an e
3180: 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
3190: 2a 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20  ** {F12104} The 
31a0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31b0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
31c0: 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54   shall be [SQLIT
31d0: 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20  E_OK] if all.** 
31e0: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
31f0: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
3200: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20  essfully and to 
3210: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
3220: 2a 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72  * {F12105} The r
3230: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
3240: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3250: 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72  shall be an appr
3260: 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20  opriate.**      
3270: 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72      non-zero [er
3280: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
3290: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
32a0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ails..**.** {F12
32b0: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d  107} If one or m
32c0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
32d0: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
32e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
32f0: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3300: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   return results 
3310: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61  and the 3rd para
3320: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  meter is not NUL
3330: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  L, then.**      
3340: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
3350: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66   function specif
3360: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
3370: 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
3380: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3390: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
33a0: 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c  ach row of resul
33b0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 30  t..**.** {F12110
33c0: 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  } If the callbac
33d0: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  k returns a non-
33e0: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20  zero value then 
33f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3400: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3410: 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c  ll abort the SQL
3420: 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73   statement it is
3430: 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75   currently evalu
3440: 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20  ating,.**       
3450: 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73     skip all subs
3460: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3470: 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72  ments, and retur
3480: 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  n [SQLITE_ABORT]
3490: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 33 7d  ..**.** {F12113}
34a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
34b0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
34c0: 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68  all pass its 4th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75   parameter throu
34e0: 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  gh.**          a
34f0: 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  s the 1st parame
3500: 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ter of the callb
3510: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ack..**.** {F121
3520: 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  16} The [sqlite3
3530: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3540: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32   shall set the 2
3550: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
3560: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3570: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74  callback to be t
3580: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
3590: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72  umns in the curr
35a0: 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20  ent row of.**   
35b0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a         result..*
35c0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 39 7d 20 54 68  *.** {F12119} Th
35d0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
35e0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
35f0: 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61 72   set the 3rd par
3600: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3610: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3620: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3630: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3640: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3650: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3660: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
3670: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
3680: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
3690: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
36a0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
36b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
36c0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
36d0: 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b  * {F12122} The [
36e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
36f0: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3700: 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  t the 4th parame
3710: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3720: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
3730: 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f  to be an array o
3740: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3750: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68  rings holding th
3760: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  e.**          na
3770: 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  mes of result co
3780: 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65  lumns as obtaine
3790: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37a0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
37b0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35 7d 20 49  **.** {F12125} I
37c0: 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
37d0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
37e0: 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20  exec()] is NULL 
37f0: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
3800: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3810: 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79  ] shall silently
3820: 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20 72   discard query r
3830: 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  esults..**.** {F
3840: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72  12131} If an err
3850: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3860: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75  parsing or evalu
3870: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65  ating any of the
3880: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
3890: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
38a0: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f  he S parameter o
38b0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
38c0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20  D,S,C,A,E)] and 
38d0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  if.**          t
38e0: 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69  he E parameter i
38f0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3900: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3910: 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a  ] shall store.**
3920: 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20            in *E 
3930: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
3940: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69  rror message wri
3950: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
3960: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
3970: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
3980: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
3990: 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20 54 68  *.** {F12134} Th
39a0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
39b0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74  D,S,C,A,E)] rout
39c0: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
39d0: 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  e value of.**   
39e0: 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c         *E to NUL
39f0: 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55  L if E is not NU
3a00: 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65  LL and there are
3a10: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a   no errors..**.*
3a20: 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65 20 5b  * {F12137} The [
3a30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3a40: 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f  ,C,A,E)] functio
3a50: 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  n shall set the 
3a60: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
3a70: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
3a80: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
3a90: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
3aa0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
3ab0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
3ac0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
3ad0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3ae0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38  ]..**.** {F12138
3af0: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3b00: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3b10: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3b20: 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a  ] is NULL or an.
3b30: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74  **          empt
3b40: 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74  y string or cont
3b50: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
3b60: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
3b70: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a  ce, comments,.**
3b80: 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72            and/or
3b90: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65   semicolons, the
3ba0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71  n results of [sq
3bb0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3bc0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3bd0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3be0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3bf0: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
3c00: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73         shall res
3c10: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e  et to indicate n
3c20: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3c30: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
3c40: 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20  ** {A12141} The 
3c50: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
3c60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3c70: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76  ()] must be an v
3c80: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a  alid and open.**
3c90: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
3ca0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3cb0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20  .**.** {A12142} 
3cc0: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
3cd0: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
3ce0: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65   be closed while
3cf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3d00: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3d10: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
3d20: 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {A12143} The cal
3d30: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
3d40: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
3d50: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
3d60: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
3d70: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
3d80: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
3d90: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
3da0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
3db0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
3dc0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3dd0: 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d  ..**.** {A12145}
3de0: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
3df0: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
3e00: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3e10: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3e20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
3e30: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
3e40: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
3e50: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3e60: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
3e70: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
3e80: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
3e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ea0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
3eb0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
3ec0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
3ed0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3ee0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
3ef0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
3f00: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
3f10: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3f20: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
3f30: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
3f40: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3f50: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3f60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f70: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
3f80: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
3f90: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
3fa0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
3fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fc0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
3fd0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3fe0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
3ff0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
4000: 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45  s {F10210}.** KE
4010: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4020: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4030: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4040: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4050: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4060: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
4070: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
4080: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
4090: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
40a0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
40b0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
40c0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
40d0: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
40e0: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  lure..**.** New 
40f0: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20  error codes may 
4100: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
4110: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
4120: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  QLite..**.** See
4130: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
4140: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
4150: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4160: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
4170: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
4180: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
4190: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
41a0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
41b0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
41c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
41d0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
41e0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
41f0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
4200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4210: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
4220: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
4230: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
4240: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
4250: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
4260: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
4270: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
4280: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4290: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
42a0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
42b0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
42c0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
42d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
42e0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
42f0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4300: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4320: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4330: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4340: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4350: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4360: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4370: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
4380: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
4390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43a0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
43b0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
43c0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
43d0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
43e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
43f0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4400: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4410: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4420: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4430: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4440: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4450: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4460: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4470: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
4480: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
4490: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
44a0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
44b0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
44c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44d0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
44e0: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
44f0: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
4500: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
4510: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4520: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4530: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4540: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4550: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4570: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4580: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4590: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
45a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45b0: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
45c0: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
45d0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
45e0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
45f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4600: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
4610: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
4620: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4630: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4640: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4650: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4660: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
4670: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
4680: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
4690: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
46a0: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
46b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
46c0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
46d0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
46e0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
46f0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
4710: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
4720: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4740: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4750: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4760: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
4770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4780: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
4790: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
47a0: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
47b0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
47c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
47d0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
47e0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
47f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4800: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
4810: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
4820: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4830: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4850: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4860: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4870: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4880: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4890: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48a0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
48b0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
48c0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
48d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
48f0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4900: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4910: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4920: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4930: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4940: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4950: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4960: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4970: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4980: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4990: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
49a0: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
49b0: 20 43 6f 64 65 73 20 7b 46 31 30 32 32 30 7d 0a   Codes {F10220}.
49c0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
49d0: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
49e0: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  e} {extended err
49f0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4a00: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4a10: 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65   result code} {e
4a20: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a30: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
4a40: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4a50: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4a60: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4a70: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4a80: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4a90: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4aa0: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4ab0: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4ac0: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
4ad0: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
4ae0: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
4af0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
4b00: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
4b10: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
4b20: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
4b30: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
4b40: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4b50: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4b60: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4b70: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4b80: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4b90: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4ba0: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4bb0: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4bc0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4bd0: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4be0: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
4bf0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
4c00: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
4c10: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
4c20: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4c30: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4c40: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4c50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4c60: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4c70: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4c80: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4c90: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
4ca0: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
4cb0: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
4cc0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4cd0: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
4ce0: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
4cf0: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
4d00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4d10: 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65   codes will be e
4d20: 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69  xpand.** over ti
4d30: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4d40: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4d60: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4d70: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4d80: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4d90: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4da0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4db0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4dc0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4dd0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4de0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4df0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4e00: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
4e10: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33  S:.**.** {F10223
4e20: 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  } The symbolic n
4e30: 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e  ame for an exten
4e40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4e50: 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a  shall contains.*
4e60: 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c  *          a rel
4e70: 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73  ated primary res
4e80: 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72  ult code as a pr
4e90: 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  efix..**.** {F10
4ea0: 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73  224} Primary res
4eb0: 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73  ult code names s
4ec0: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73  hall contain a s
4ed0: 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63  ingle "_" charac
4ee0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ter..**.** {F102
4ef0: 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73  25} Extended res
4f00: 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73  ult code names s
4f10: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f  hall contain two
4f20: 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61   or more "_" cha
4f30: 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
4f40: 46 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65  F10226} The nume
4f50: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
4f60: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4f70: 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61  code shall conta
4f80: 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
4f90: 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65     numeric value
4fa0: 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f   of its correspo
4fb0: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
4fc0: 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20  sult code in.** 
4fd0: 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61           its lea
4fe0: 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38  st significant 8
4ff0: 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e   bits..*/.#defin
5000: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5010: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5020: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5030: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5040: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5050: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
5060: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5070: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
5090: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
50b0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
50c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
50d0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
50e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
50f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5100: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5110: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5120: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5130: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5140: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
5150: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
5160: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
5170: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5180: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
5190: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
51f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5200: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5210: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5220: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5240: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
5250: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5260: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
5270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5280: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
5290: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52a0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
52b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52c0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
52d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52e0: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
52f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5300: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5310: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5320: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5340: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
5350: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
5360: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
5370: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5380: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5390: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
53a0: 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10230}.**.** 
53b0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
53c0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
53d0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
53e0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
53f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5400: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5410: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5420: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5430: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
5440: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
5450: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
5460: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5470: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5480: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5490: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
54a0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
54b0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
54c0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
54d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
54e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
54f0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5500: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5510: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5520: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5530: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
5540: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5550: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
5570: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5580: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5590: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
55a0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55b0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
55c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
55d0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
55e0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5600: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5610: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
5620: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
5630: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5640: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
5650: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
5660: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
5670: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
5680: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
5690: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
56a0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
56b0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
56c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 46  aracteristics {F
56d0: 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10240}.**.** The
56e0: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
56f0: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
5700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5710: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
5720: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
5730: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
5740: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68  vector of the th
5750: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
5760: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
5770: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
5780: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
5790: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
57a0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
57b0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
57c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
57d0: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
57e0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
57f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
5800: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5810: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
5820: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
5830: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
5840: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
5850: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
5860: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
5870: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
5880: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
5890: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
58a0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
58b0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
58c0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
58d0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
58e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
58f0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5900: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
5910: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
5920: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
5930: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
5940: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
5950: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
5960: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
5970: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
5980: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
5990: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
59a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
59b0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
59c0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
59d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
59e0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
59f0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
5a00: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
5a10: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23  o xWrite()..*/.#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5a30: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5a40: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5a60: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5a70: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
5a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5a90: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
5aa0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
5ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ac0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
5ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5af0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5b00: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
5b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5b20: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
5b30: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
5b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5b50: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
5b60: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5b80: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
5b90: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5bb0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bc0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5be0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5bf0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c10: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5c20: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a      0x00000400..
5c30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c40: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
5c50: 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a  els {F10250}.**.
5c60: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5c70: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5c80: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5c90: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ca0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5cb0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5cc0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5cd0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5ce0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5cf0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5d00: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5d10: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5d20: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5d30: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5d40: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5d60: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5d90: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5da0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5db0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5dc0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
5dd0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
5de0: 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a  lags {F10260}.**
5df0: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5e00: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5e10: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5e20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5e30: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5e40: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5e50: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5e60: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5e70: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5e80: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5e90: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5ea0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5eb0: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5ec0: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5ed0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5ee0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5ef0: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5f00: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5f10: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5f20: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5f30: 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53  ed. The SQLITE_S
5f40: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20  YNC_NORMAL flag 
5f50: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
5f60: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5f70: 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 53 51  emantics. The SQ
5f80: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
5f90: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
5fa0: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  use Mac OS-X sty
5fb0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
5fc0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
5ff0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6010: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6020: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6030: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6040: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6050: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6060: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
6070: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20  pen File Handle 
6080: 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F11110}.**.** A
6090: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
60a0: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
60b0: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
60c0: 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74  in the OS.** int
60d0: 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49  erface layer.  I
60e0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
60f0: 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74  erface implement
6100: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
6110: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
6120: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
6130: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
6140: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
6150: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
6160: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
6170: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
6180: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
6190: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
61a0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
61b0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
61c0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
61d0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
61e0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
61f0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6200: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
6210: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
6220: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
6230: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
6240: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6250: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
6260: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
6270: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
6280: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
6290: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
62a0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
62b0: 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 31  hods Object {F11
62c0: 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  120}.**.** Every
62d0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
62e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
62f0: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70  ] xOpen method p
6300: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
6310: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6320: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
6330: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
6340: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
6350: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6360: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6370: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6380: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
6390: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
63a0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
63b0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
63c0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
63d0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
63e0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
63f0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
6400: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6410: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
6420: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
6430: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
6440: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
6450: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
6460: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
6470: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
6480: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
6490: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
64a0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
64b0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
64c0: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
64d0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
64e0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
64f0: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
6500: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
6510: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
6520: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
6530: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
6540: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
6550: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
6560: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
6570: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
6580: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6590: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
65a0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
65b0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
65c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
65d0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6600: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6610: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6630: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6640: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6650: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
6660: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
6670: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
6680: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
6690: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
66a0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
66b0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
66c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
66d0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
66e0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
66f0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
6700: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
6710: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
6720: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
6730: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
6740: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
6750: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
6760: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
6770: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
6780: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
6790: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
67a0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
67b0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
67c0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
67d0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
67e0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
67f0: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
6800: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
6810: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
6820: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
6830: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
6840: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
6850: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
6860: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
6870: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
6880: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
6890: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
68a0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
68b0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
68c0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
68d0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
68e0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
68f0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
6900: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
6910: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
6920: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
6930: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
6940: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
6950: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
6960: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
6970: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
6980: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
6990: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
69a0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
69b0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
69c0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
69d0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
69e0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
69f0: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
6a00: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
6a10: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
6a20: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
6a30: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
6a40: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
6a50: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
6a60: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
6a70: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
6a80: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
6a90: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
6aa0: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
6ab0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
6ac0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
6ad0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
6ae0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
6af0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ts..**.** The xS
6b00: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
6b10: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
6b20: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
6b30: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6b40: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
6b50: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
6b60: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
6b70: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
6b80: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
6b90: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
6ba0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
6bb0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
6bc0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
6bd0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
6be0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
6bf0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
6c00: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
6c10: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
6c20: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
6c30: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
6c40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6c50: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
6c60: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c70: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
6c80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6c90: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
6ca0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6cb0: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
6cc0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6cd0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
6ce0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6cf0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
6d40: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6d50: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
6d60: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6d70: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6d80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d90: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6da0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
6db0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
6dc0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
6dd0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
6de0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
6df0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
6e00: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6e10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
6e20: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
6e30: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
6e40: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
6e50: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
6e60: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
6e70: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
6e80: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
6e90: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
6ea0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
6eb0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6ec0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6ed0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
6ee0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
6ef0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
6f00: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
6f10: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
6f20: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
6f30: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
6f40: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
6f50: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
6f60: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6f80: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6fa0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
6fb0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
6fc0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
6fd0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
6fe0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70  xWrite()..*/.typ
6ff0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7000: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7010: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7020: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7030: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7040: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7050: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
7060: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7070: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
7080: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
7090: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
70a0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
70b0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
70c0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
70d0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
70e0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
70f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7100: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7110: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7120: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7130: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7140: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7150: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
7160: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
7170: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7180: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7190: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
71a0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
71b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
71c0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
71d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
71e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
71f0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7210: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7220: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7230: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7240: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7250: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7260: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7270: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7280: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7290: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
72a0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
72b0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
72c0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
72d0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
72e0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
72f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7300: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7310: 6c 20 4f 70 63 6f 64 65 73 20 7b 46 31 31 33 31  l Opcodes {F1131
7320: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  0}.**.** These i
7330: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
7340: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
7350: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7360: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
7370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
7380: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
7390: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
73a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
73b0: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
73c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
73d0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
73e0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
73f0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
7400: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
7410: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
7420: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7430: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
7440: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
7450: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
7460: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
7470: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
7480: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7490: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
74a0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
74b0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
74c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
74d0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
74e0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
74f0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
7500: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
7510: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
7520: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
7530: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
7540: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
7550: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
7560: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
7570: 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65   defined..*/.#de
7580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
7590: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
75a0: 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     1../*.** CAPI
75b0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
75c0: 6c 65 20 7b 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a  le {F17110}.**.*
75d0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
75e0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
75f0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
7600: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
7610: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
7620: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
7630: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
7640: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
7650: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
7660: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
7670: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
7680: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
7690: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
76a0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
76b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
76c0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
76d0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
76e0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
76f0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
7700: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
7710: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
7720: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
7730: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
7740: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7750: 65 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 34 30  e Object {F11140
7760: 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
7770: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
7780: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
7790: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
77a0: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
77b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
77c0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
77d0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
77e0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
77f0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
7800: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
7810: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
7820: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
7830: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
7840: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
7850: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
7860: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
7870: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
7880: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
7890: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
78a0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
78b0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
78c0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
78d0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
78e0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
78f0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
7900: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
7910: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7920: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
7930: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
7940: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
7950: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
7960: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
7970: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
7980: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
7990: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
79a0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
79b0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
79c0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
79d0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
79e0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
79f0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
7a00: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
7a10: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
7a20: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
7a30: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
7a40: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
7a50: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
7a60: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
7a70: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
7a80: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
7a90: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
7aa0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
7ab0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
7ac0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
7ad0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
7ae0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
7af0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
7b00: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
7b10: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
7b20: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
7b30: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
7b40: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
7b50: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
7b60: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
7b70: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
7b80: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
7b90: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
7ba0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
7bb0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
7bc0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
7bd0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
7be0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
7bf0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
7c00: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
7c10: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
7c20: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
7c30: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
7c40: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
7c50: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
7c60: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
7c70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
7c80: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
7c90: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
7ca0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
7cb0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
7cc0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
7cd0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
7ce0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
7cf0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
7d00: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
7d10: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
7d20: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
7d30: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
7d40: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
7d50: 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74 65   {F11141} SQLite
7d60: 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20   will guarantee 
7d70: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
7d80: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
7d90: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
7da0: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
7db0: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
7dc0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
7dd0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53  llPathname().  S
7de0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
7df0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
7e00: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
7e10: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
7e20: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
7e30: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
7e40: 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63 61  led. {END}  Beca
7e50: 73 75 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  sue of the previ
7e60: 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 20 0a 2a  ous sentense, .*
7e70: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
7e80: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
7e90: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
7ea0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
7eb0: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
7ec0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
7ed0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
7ee0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
7ef0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
7f00: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20  ameter is xOpen 
7f10: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
7f20: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
7f30: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20  must invite its 
7f40: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
7f50: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
7f60: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a    Whenever the .
7f70: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
7f80: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
7f90: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
7fa0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
7fb0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
7fc0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
7fd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7fe0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
7ff0: 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65  .** {F11142} The
8000: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8010: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
8020: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
8030: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
8040: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
8050: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
8060: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
8070: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8080: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8090: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
80a0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
80b0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
80c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
80d0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
80e0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44  EN_CREATE]. {END
80f0: 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  }.** If xOpen() 
8100: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8110: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8120: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
8130: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
8140: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
8150: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
8160: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
8170: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
8180: 20 7b 46 31 31 31 34 33 7d 20 53 51 4c 69 74 65   {F11143} SQLite
8190: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
81a0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
81b0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
81c0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
81d0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
81e0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
81f0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
8200: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
8210: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
8220: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8230: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
8240: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8250: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8260: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8280: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8290: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
82a0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
82b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
82c0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
82d0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
82e0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
82f0: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NAL].** </ul> {E
8300: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ND}.**.** The fi
8310: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
8320: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
8330: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
8340: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
8350: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
8360: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
8370: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
8380: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
8390: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
83a0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
83b0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
83c0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
83d0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
83e0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
83f0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
8400: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
8410: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
8420: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
8430: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
8440: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
8450: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
8460: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
8470: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
8480: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
8490: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
84a0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
84b0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
84c0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
84d0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
84e0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
84f0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
8500: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
8510: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
8520: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
8530: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
8540: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
8550: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
8560: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
8570: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8580: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8590: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
85a0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
85b0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
85c0: 2a 20 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b  * {F11145} The [
85d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
85e0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
85f0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
8600: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
8610: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8620: 6c 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d  losed.  {F11146}
8630: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8640: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8650: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8660: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8670: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8680: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8690: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 37  s..**.** {F11147
86a0: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
86b0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
86c0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
86d0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
86e0: 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  ed.** for exclus
86f0: 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69  ive access.  Thi
8700: 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f  s flag is set fo
8710: 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65  r all files exce
8720: 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61  pt.** for the ma
8730: 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
8740: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 38 7d  ..**.** {F11148}
8750: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
8760: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
8770: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
8780: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
8790: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
87a0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
87b0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
87c0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
87d0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45  ent to xOpen. {E
87e0: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ND}  The xOpen m
87f0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
8800: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
8810: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
8820: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
8830: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a   fill it in..**.
8840: 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20  ** {F11149} The 
8850: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8860: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8870: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8880: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
8890: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
88a0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
88b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
88c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
88d0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
88e0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
88f0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8900: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
8910: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8920: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8930: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8940: 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d   readable. {END}
8950: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8960: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8970: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 35 30 7d  ..**.** {F11150}
8980: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8990: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
89a0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
89b0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
89c0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
89d0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
89e0: 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65 78   {F11151} The ex
89f0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
8a00: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8a10: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
8a20: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
8a30: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
8a40: 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f   {END}  If the o
8a50: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8a60: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8a70: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8a80: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8a90: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8aa0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8ab0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8ac0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8ad0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8ae0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8af0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8b00: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8b10: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8b20: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8b30: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8b40: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8b50: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8b60: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8b70: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8b80: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8b90: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ba0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8bb0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8bc0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8bd0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8be0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8bf0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8c00: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8c10: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8c20: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8c30: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8c40: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8c50: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8c60: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8c70: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8c80: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8c90: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8ca0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8cb0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8cc0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
8cd0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8ce0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8cf0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8d00: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8d10: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8d20: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8d30: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8d40: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8d50: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8d60: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8d70: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8d80: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
8d90: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8da0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8db0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
8dc0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
8dd0: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e  n number */.  in
8de0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
8df0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
8e00: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
8e10: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
8e20: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
8e30: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
8e40: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
8e50: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
8e60: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
8e70: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
8e80: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
8e90: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
8ea0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
8eb0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
8ec0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
8ed0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
8ee0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
8ef0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
8f00: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
8f10: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
8f20: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
8f30: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8f40: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
8f50: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
8f60: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
8f70: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
8f80: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
8f90: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8fa0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
8fb0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
8fc0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
8fd0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
8fe0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
8ff0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
9000: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
9010: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9020: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9030: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9040: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9050: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9060: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9070: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9080: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9090: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
90a0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
90b0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
90c0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
90d0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
90e0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
90f0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
9100: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
9110: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
9120: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
9130: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
9140: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
9150: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9160: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
9170: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9180: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9190: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
91a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
91b0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
91c0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
91d0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
91e0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
91f0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
9200: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
9210: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9220: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
9230: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
9240: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
9250: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
9260: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
9270: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
9280: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9290: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
92a0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b  ess VFS method {
92b0: 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F11190}.**.** {F
92c0: 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74  11191} These int
92d0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
92e0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
92f0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
9300: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
9310: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
9320: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
9330: 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68  bject. {END}  Th
9340: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
9350: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
9360: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
9370: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
9380: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b  ooking for..** {
9390: 46 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c  F11192} With SQL
93a0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
93b0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
93c0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
93d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
93e0: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
93f0: 2a 2a 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68  ** {F11193} With
9400: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9410: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
9420: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9430: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9440: 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20  he file is both 
9450: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9460: 74 61 62 6c 65 2e 0a 2a 2a 20 7b 46 31 31 31 39  table..** {F1119
9470: 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  4} With SQLITE_A
9480: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
9490: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
94a0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
94b0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
94c0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
94d0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
94e0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
94f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9500: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
9510: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
9520: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
9530: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9540: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
9550: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9560: 46 31 30 31 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10130}.**.** Th
9570: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9580: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9590: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
95a0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
95b0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
95c0: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
95d0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
95e0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
95f0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
9600: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
9610: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a  itialize()..**.*
9620: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
9630: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9640: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
9650: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
9660: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
9670: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
9680: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
9690: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
96a0: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
96b0: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
96c0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
96d0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
96e0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
96f0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
9700: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
9710: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9720: 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69   Only an effecti
9730: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
9740: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9750: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
9760: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
9770: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
9780: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
9790: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  ops..**.** Among
97a0: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73   other things, s
97b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
97c0: 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  e() shall invoke
97d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
97e0: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
97f0: 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y, sqlite3_shutd
9800: 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69  own().** shall i
9810: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
9820: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  _end()..**.** Th
9830: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9840: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9850: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
9860: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
9870: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
9880: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
9890: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
98a0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
98b0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
98c0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
98d0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
98e0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
98f0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
9900: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
9910: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
9920: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51  e] other than SQ
9930: 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54  LITE_OK..**.** T
9940: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9950: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9960: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
9970: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
9980: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
9990: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
99a0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
99b0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
99c0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
99d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
99e0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
99f0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
9a00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
9a10: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
9a20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
9a30: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
9a40: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
9a50: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
9a60: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
9a70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
9a80: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
9a90: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
9aa0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
9ab0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  .  However, if S
9ac0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9ad0: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
9ae0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a  E_OMIT_AUTOINIT.
9af0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
9b00: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
9b10: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
9b20: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
9b30: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
9b40: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
9b50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
9b60: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
9b70: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9b80: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
9b90: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
9ba0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9bb0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
9bc0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
9bd0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
9be0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
9bf0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
9c00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9c10: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
9c20: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
9c30: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
9c40: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
9c50: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
9c60: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
9c70: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
9c80: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
9c90: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
9ca0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
9cb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9cc0: 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54  with SQLITE_OMIT
9cd0: 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20  _AUTOINIT might 
9ce0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
9cf0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
9d00: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
9d10: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
9d20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
9d30: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
9d40: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
9d50: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
9d60: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
9d70: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
9d80: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
9d90: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
9da0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
9db0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
9dc0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
9dd0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
9de0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
9df0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
9e00: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
9e10: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
9e20: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
9e30: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
9e40: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
9e50: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
9e60: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
9e70: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
9e80: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
9e90: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
9ea0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
9eb0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
9ec0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
9ed0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
9ee0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
9ef0: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
9f00: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
9f10: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
9f20: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
9f30: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
9f40: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
9f50: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
9f60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f70: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
9f80: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
9f90: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9fa0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
9fb0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
9fc0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
9fd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9fe0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
9ff0: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
a000: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
a010: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
a020: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
a030: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
a040: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a050: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a060: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
a070: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
a080: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
a090: 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f   for unix, windo
a0a0: 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20  ws, or os/2..** 
a0b0: 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f  When built for o
a0c0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28  ther platforms (
a0d0: 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
a0e0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70  _OS_OTHER=1 comp
a0f0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
a100: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
a110: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
a120: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
a130: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
a140: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a150: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
a160: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
a170: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
a180: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
a190: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
a1a0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
a1b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a1c0: 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49  must return SQLI
a1d0: 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73  TE_OK on success
a1e0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
a1f0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
a200: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
a210: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
a220: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
a230: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
a240: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
a250: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
a260: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
a270: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
a280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a290: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
a2a0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
a2b0: 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a 20 54  {F10145}.**.** T
a2c0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
a2d0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
a2e0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
a2f0: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
a300: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
a310: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
a320: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
a330: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
a340: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
a350: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
a360: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
a370: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
a380: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
a390: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
a3a0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
a3b0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
a3c0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
a3d0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
a3e0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
a3f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
a400: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
a410: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
a420: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
a430: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
a440: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
a450: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
a460: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
a470: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
a480: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
a490: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
a4a0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
a4b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a4c0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
a4d0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
a4e0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
a4f0: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
a500: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
a510: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
a520: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
a530: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a540: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
a550: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
a560: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
a570: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
a580: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
a590: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
a5a0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
a5b0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
a5c0: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
a5d0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
a5e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a5f0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
a600: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
a610: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a620: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
a630: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
a640: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
a650: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a660: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
a670: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
a680: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
a690: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
a6a0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
a6b0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
a6c0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
a6d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
a6e0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a6f0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a700: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
a710: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a720: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
a730: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a740: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
a750: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
a760: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
a770: 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f  .** If the optio
a780: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
a790: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
a7a0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
a7b0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
a7c0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
a7d0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
a7e0: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
a7f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
a800: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
a810: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
a820: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
a830: 74 69 6e 65 73 20 7b 46 31 30 31 35 35 7d 0a 2a  tines {F10155}.*
a840: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
a850: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a860: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a870: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
a880: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
a890: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
a8a0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
a8b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
a8c0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
a8d0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
a8e0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
a8f0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
a900: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
a910: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a920: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a930: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
a940: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
a950: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a960: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a970: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a980: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
a990: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
a9a0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
a9b0: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
a9c0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
a9d0: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
a9e0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
a9f0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
aa00: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
aa10: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
aa20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
aa30: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
aa40: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
aa50: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
aa60: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
aa70: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
aa80: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
aa90: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
aaa0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
aab0: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
aac0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
aad0: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
aae0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
aaf0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
ab00: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
ab10: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
ab20: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
ab30: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
ab40: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
ab50: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
ab60: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
ab70: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
ab80: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
ab90: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
aba0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
abb0: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
abc0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
abd0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
abe0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
abf0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
ac00: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
ac10: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
ac20: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
ac30: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
ac40: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
ac50: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ac60: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ac70: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
ac80: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
ac90: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
aca0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
acb0: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
acc0: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
acd0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
ace0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
acf0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
ad00: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
ad10: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
ad20: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ad30: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
ad40: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
ad50: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
ad60: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
ad70: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
ad80: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
ad90: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
ada0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
adb0: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
adc0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
add0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
ade0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
adf0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
ae00: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
ae10: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
ae20: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
ae30: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
ae40: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
ae50: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
ae60: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ae70: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
ae80: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
ae90: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
aea0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
aeb0: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
aec0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
aed0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
aee0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
aef0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
af00: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
af10: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
af20: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
af30: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
af40: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
af50: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
af60: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
af70: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
af80: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
af90: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
afa0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
afb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
afc0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
afd0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
afe0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
aff0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
b000: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
b010: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
b020: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
b030: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
b040: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
b050: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b060: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b070: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b080: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
b090: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b0a0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
b0b0: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
b0c0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
b0d0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
b0e0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
b0f0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
b100: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
b110: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
b120: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
b130: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
b140: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
b150: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
b160: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
b170: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b180: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
b190: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
b1a0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
b1b0: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
b1c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
b1d0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
b1e0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
b1f0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
b200: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
b210: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
b220: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
b230: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
b240: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
b250: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
b260: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
b270: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b280: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
b290: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
b2a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
b2b0: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
b2c0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
b2d0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b2e0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
b2f0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 46 31  tion Options {F1
b300: 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0160}.**.** Thes
b310: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
b320: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
b330: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
b340: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
b350: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
b360: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
b370: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
b380: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b390: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
b3a0: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
b3b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
b3c0: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
b3d0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
b3e0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
b3f0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
b400: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
b410: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
b420: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
b430: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
b440: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
b450: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
b460: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
b470: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
b480: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
b490: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
b4a0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
b4b0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
b4c0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
b4d0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
b4e0: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
b4f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b500: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
b510: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
b520: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
b530: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
b540: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
b550: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
b560: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
b570: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
b580: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
b590: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
b5a0: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
b5b0: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
b5c0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
b5d0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
b5e0: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
b5f0: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
b600: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
b610: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b620: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
b630: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
b640: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
b650: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
b660: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
b670: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
b680: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
b690: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
b6a0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
b6b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b6c0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b6d0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
b6e0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
b6f0: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
b700: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
b710: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
b720: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
b730: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
b740: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
b750: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
b760: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
b770: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
b780: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
b790: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b7a0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
b7b0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
b7c0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
b7d0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
b7e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
b7f0: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
b800: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
b810: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
b820: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
b830: 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e time.</dd>.**.
b840: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b850: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
b860: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
b870: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
b880: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
b890: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
b8a0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
b8b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
b8c0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
b8d0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
b8e0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
b8f0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
b900: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
b910: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
b920: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
b930: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
b940: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
b950: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
b960: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
b970: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b980: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
b990: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
b9a0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b9b0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
b9c0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
b9d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b9e0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
b9f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
ba00: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
ba10: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
ba20: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
ba30: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
ba40: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
ba50: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
ba60: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ba70: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
ba80: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
ba90: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
baa0: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
bab0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bac0: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
bad0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
bae0: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
baf0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bb00: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
bb10: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
bb20: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
bb30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bb40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
bb50: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
bb60: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bb70: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f  takes single boo
bb80: 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68  lean argument wh
bb90: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
bba0: 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63  isables.** the c
bbb0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
bbc0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
bbd0: 74 61 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e  tatistics.  When
bbe0: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a   disabled, the.*
bbf0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
bc00: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
bc10: 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
bc20: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
bc30: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
bc40: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
bc50: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
bc60: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
bc70: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
bc80: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
bc90: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
bca0: 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  *   <li> sqlite3
bcb0: 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29  _memory_status()
bcc0: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
bcd0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bce0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
bcf0: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
bd00: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
bd10: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
bd20: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
bd30: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
bd40: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
bd50: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
bd60: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
bd70: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
bd80: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
bd90: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
bda0: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
bdb0: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
bdc0: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
bdd0: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
bde0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
bdf0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
be00: 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a   16. The first.*
be10: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
be20: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
be30: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
be40: 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79  east (sz+4)*N by
be50: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
be60: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
be70: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e no more than o
be80: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
be90: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68  r at once per th
bea0: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68  read, so.** N sh
beb0: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
bec0: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
bed0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
bee0: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a  reads.  The sz.*
bef0: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  * parameter shou
bf00: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68  ld be 6 times th
bf10: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
bf20: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
bf30: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72  age size..** Scr
bf40: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65  atch buffers are
bf50: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66   used as part of
bf60: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   the btree balan
bf70: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49  ce operation.  I
bf80: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62  f.** The btree b
bf90: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64  alancer needs ad
bfa0: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
bfb0: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
bfc0: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63  rovided by.** sc
bfd0: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72  ratch buffers or
bfe0: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62   if no scratch b
bff0: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73  uffer space is s
c000: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53  pecified, then S
c010: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f  QLite.** goes to
c020: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c030: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  ()] to obtain th
c040: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64  e memory it need
c050: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
c060: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c070: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
c080: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c090: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
c0a0: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
c0b0: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
c0c0: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
c0d0: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
c0e0: 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72  cache.  There ar
c0f0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
c100: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
c110: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  the.** memory, t
c120: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
c130: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
c140: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
c150: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
c160: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
c170: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65  t must be a powe
c180: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
c190: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20   512 and 32768. 
c1a0: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
c1b0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c1c0: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
c1d0: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
c1e0: 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20   (sz+4)*N bytes 
c1f0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51  of memory..** SQ
c200: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
c210: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
c220: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
c230: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
c240: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
c250: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
c260: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
c270: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
c280: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e  he.  If addition
c290: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
c2a0: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
c2b0: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
c2c0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
c2d0: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
c2e0: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
c2f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c300: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
c310: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
c320: 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
c330: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c340: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
c350: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c360: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c370: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c380: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c390: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
c3a0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
c3b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c3c0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
c3d0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
c3e0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
c3f0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
c400: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
c410: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
c420: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
c430: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
c440: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
c450: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72  mory, the number
c460: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
c470: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
c480: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
c490: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
c4a0: 7a 65 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 69  ze.  When.** thi
c4b0: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
c4c0: 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2c 20  option is used, 
c4d0: 53 51 4c 69 74 65 20 6e 65 76 65 72 20 63 61 6c  SQLite never cal
c4e0: 6c 73 20 74 68 65 20 73 79 73 74 65 6d 0a 2a 2a  ls the system.**
c4f0: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
c500: 65 6e 74 61 74 69 6f 6e 20 62 75 74 20 69 6e 73  entation but ins
c510: 74 65 61 64 20 75 73 65 73 20 74 68 65 20 73 75  tead uses the su
c520: 70 70 6c 69 65 64 20 6d 65 6d 6f 72 79 20 62 75  pplied memory bu
c530: 66 66 65 72 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ffer.** to satis
c540: 66 79 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  fy all [sqlite3_
c550: 6d 61 6c 6c 6f 63 28 29 5d 20 72 65 71 75 65 73  malloc()] reques
c560: 74 73 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  ts. This option 
c570: 69 73 20 6f 6e 6c 79 0a 2a 2a 20 61 76 61 69 6c  is only.** avail
c580: 61 62 6c 65 20 69 66 20 65 69 74 68 65 72 20 6f  able if either o
c590: 72 20 62 6f 74 68 20 6f 66 20 53 51 4c 49 54 45  r both of SQLITE
c5a0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 20  _ENABLE_MEMSYS3 
c5b0: 61 6e 64 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45  and .** SQLITE_E
c5c0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 20 61 72  NABLE_MEMSYS5 ar
c5d0: 65 20 64 65 66 69 6e 65 64 20 64 75 72 69 6e 67  e defined during
c5e0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 2e 3c 2f 64   compilation.</d
c5f0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c600: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
c610: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c620: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
c630: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c640: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
c650: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
c660: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
c670: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c680: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c690: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
c6a0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
c6b0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
c6c0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
c6d0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c6e0: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
c6f0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
c700: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
c710: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c720: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
c730: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
c740: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
c750: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
c760: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
c770: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
c780: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
c790: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
c7a0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c7b0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
c7c0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
c7d0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
c7e0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
c7f0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
c800: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
c810: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
c820: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
c830: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
c840: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
c850: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
c860: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
c870: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
c880: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
c890: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
c8a0: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
c8b0: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
c8c0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
c8d0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c8e0: 5f 4d 45 4d 53 59 53 33 3c 2f 64 74 3e 0a 2a 2a  _MEMSYS3</dt>.**
c8f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c900: 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
c910: 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
c920: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
c930: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  e .** SQLITE_ENA
c940: 42 4c 45 5f 4d 45 4d 53 59 53 33 20 73 79 6d 62  BLE_MEMSYS3 symb
c950: 6f 6c 20 64 65 66 69 6e 65 64 2e 20 49 74 20 73  ol defined. It s
c960: 65 6c 65 63 74 73 20 6f 6e 65 20 6f 66 20 74 77  elects one of tw
c970: 6f 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  o memory.** allo
c980: 63 61 74 69 6f 6e 20 73 79 73 74 65 6d 73 20 74  cation systems t
c990: 68 61 74 20 75 73 65 20 74 68 65 20 62 6c 6f 63  hat use the bloc
c9a0: 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 73 75 70 70  k of memory supp
c9b0: 6c 69 65 64 20 74 6f 20 73 71 6c 69 74 65 20 0a  lied to sqlite .
c9c0: 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ** using the SQL
c9d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
c9e0: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 64 3e  option..** </dd>
c9f0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ca00: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 59 53 35  E_CONFIG_MEMSYS5
ca10: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
ca20: 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
ca30: 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
ca40: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ca50: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
ca60: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
ca70: 59 53 35 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  YS5 symbol defin
ca80: 65 64 2e 20 49 74 20 73 65 6c 65 63 74 73 20 6f  ed. It selects o
ca90: 6e 65 20 6f 66 20 74 77 6f 20 6d 65 6d 6f 72 79  ne of two memory
caa0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
cab0: 79 73 74 65 6d 73 20 74 68 61 74 20 75 73 65 20  ystems that use 
cac0: 74 68 65 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  the block of mem
cad0: 6f 72 79 20 73 75 70 70 6c 69 65 64 20 74 6f 20  ory supplied to 
cae0: 73 71 6c 69 74 65 20 0a 2a 2a 20 75 73 69 6e 67  sqlite .** using
caf0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
cb00: 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 2e 20  IG_HEAP option. 
cb10: 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
cb20: 61 74 69 6f 6e 20 73 79 73 74 65 6d 0a 2a 2a 20  ation system.** 
cb30: 73 65 6c 65 63 74 65 64 20 62 79 20 74 68 69 73  selected by this
cb40: 20 6f 70 74 69 6f 6e 2c 20 22 6d 65 6d 73 79 73   option, "memsys
cb50: 35 22 2c 20 69 73 20 61 6c 73 6f 20 69 6e 73 74  5", is also inst
cb60: 61 6c 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  alled by default
cb70: 20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 53 51   .** when the SQ
cb80: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
cb90: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
cba0: 73 6f 20 69 74 20 69 73 20 6e 6f 74 20 75 73 75  so it is not usu
cbb0: 61 6c 6c 79 0a 2a 2a 20 6e 65 63 65 73 73 61 72  ally.** necessar
cbc0: 79 20 74 6f 20 75 73 65 20 74 68 69 73 20 6f 70  y to use this op
cbd0: 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 2e 0a 2a  tion directly..*
cbe0: 2a 20 3c 2f 64 64 3e 0a 2a 2f 0a 23 64 65 66 69  * </dd>.*/.#defi
cbf0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cc00: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
cc10: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
cc20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
cc30: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
cc40: 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
cc50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
cc60: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
cc70: 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
cc80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cc90: 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
cca0: 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
ccb0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
ccc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ccd0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
cce0: 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
ccf0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
cd00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cd10: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
cd20: 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
cd30: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
cd40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cd50: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
cd60: 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
cd70: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
cd80: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
cd90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
cda0: 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
cdb0: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
cdc0: 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
cdd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
cde0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
cdf0: 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
ce00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ce10: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
ce20: 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
ce30: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
ce40: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
ce50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
ce60: 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
ce70: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
ce80: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
ce90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cea0: 4d 45 4d 53 59 53 33 20 20 20 20 20 20 31 32 20  MEMSYS3      12 
ceb0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
cec0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ced0: 5f 4d 45 4d 53 59 53 35 20 20 20 20 20 20 31 33  _MEMSYS5      13
cee0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 0a 2f 2a 0a    /* nil */../*.
cef0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
cf00: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
cf10: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
cf20: 6f 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a  odes {F12200}.**
cf30: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
cf40: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
cf50: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
cf60: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
cf70: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
cf80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
cf90: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
cfa0: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
cfb0: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
cfc0: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
cfd0: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
cfe0: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
cff0: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
d000: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ations..**.** IN
d010: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
d020: 7b 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65  {F12201} Each ne
d030: 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
d040: 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61  ection] shall ha
d050: 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ve the.**       
d060: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
d070: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
d080: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
d090: 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  efault..**.** {F
d0a0: 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12202} The [sqli
d0b0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
d0c0: 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20  ult_codes(D,F)] 
d0d0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
d0e0: 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  enable.**       
d0f0: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
d100: 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74  ult codes] for t
d110: 68 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f  he  [database co
d120: 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
d130: 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46          if the F
d140: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72   parameter is tr
d150: 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ue, or disable t
d160: 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73  hem if F is fals
d170: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
d180: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
d190: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
d1a0: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
d1b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
d1c0: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
d1d0: 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F12220}.**.** 
d1e0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
d1f0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
d200: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
d210: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
d220: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
d230: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
d240: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
d250: 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
d260: 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
d270: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
d280: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
d290: 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
d2a0: 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
d2b0: 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
d2c0: 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
d2d0: 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66  ared columns. If
d2e0: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
d2f0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
d300: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
d310: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
d320: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
d330: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
d340: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
d350: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
d360: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20  turns the rowid 
d370: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
d380: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
d390: 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65   INSERT into the
d3a0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
d3b0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
d3c0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
d3d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d3e0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
d3f0: 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20  sful INSERTs.** 
d400: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
d410: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
d420: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
d430: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
d440: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
d450: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
d460: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
d470: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
d480: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
d490: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
d4a0: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
d4b0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
d4c0: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
d4d0: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
d4e0: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
d4f0: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
d500: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
d510: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
d520: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
d530: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
d540: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
d550: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
d560: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
d570: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
d580: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
d590: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
d5a0: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
d5b0: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
d5c0: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
d5d0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
d5e0: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
d5f0: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
d600: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
d610: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
d620: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
d630: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
d640: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
d650: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
d660: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
d670: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
d680: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
d690: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
d6a0: 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
d6b0: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
d6c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
d6d0: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
d6e0: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
d6f0: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
d700: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
d710: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
d720: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
d730: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
d740: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
d750: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
d760: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
d770: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
d780: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
d790: 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
d7a0: 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
d7b0: 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53   routine, an INS
d7c0: 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ERT is considere
d7d0: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
d7e0: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
d7f0: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
d800: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
d810: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
d820: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20 54  **.** {F12221} T
d830: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
d840: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d850: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
d860: 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20  s the rowid.**  
d870: 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d          of the m
d880: 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
d890: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72  ssful INSERT per
d8a0: 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
d8b0: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  me.**          [
d8c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d8d0: 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20  ion] and within 
d8e0: 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
d8f0: 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20  er level.**     
d900: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
d910: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
d920: 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e   there have been
d930: 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69   no qualifying i
d940: 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nserts..**.** {F
d950: 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  12223} The [sqli
d960: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
d970: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
d980: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
d990: 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76            same v
d9a0: 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64  alue when called
d9b0: 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
d9c0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a  rigger context.*
d9d0: 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64  *          immed
d9e0: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e  iately before an
d9f0: 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41  d after a ROLLBA
da00: 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  CK..**.** LIMITA
da10: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
da20: 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72  2232} If a separ
da30: 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
da40: 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54  rms a new INSERT
da50: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
da60: 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
da70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
da80: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
da90: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
daa0: 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  d()].**         
dab0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
dac0: 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
dad0: 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
dae0: 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20  nsert rowid,.** 
daf0: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
db00: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
db10: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
db20: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
db30: 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
db40: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
db50: 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
db60: 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
db70: 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
db80: 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e           last in
db90: 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73  sert rowid..*/.s
dba0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
dbb0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
dbc0: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
dbd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
dbe0: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
dbf0: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
dc00: 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a  fied {F12240}.**
dc10: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
dc20: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
dc30: 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
dc40: 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
dc50: 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
dc60: 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
dc70: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
dc80: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
dc90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
dca0: 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
dcb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
dcc0: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
dcd0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
dce0: 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  .** Only changes
dcf0: 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
dd00: 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
dd10: 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
dd20: 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54 45  TE,.** or DELETE
dd30: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
dd40: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
dd50: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
dd60: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
dd70: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
dd80: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
dd90: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
dda0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
ddb0: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
ddc0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
ddd0: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
dde0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
ddf0: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
de00: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
de10: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
de20: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
de30: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
de40: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
de50: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
de60: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
de70: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
de80: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
de90: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
dea0: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
deb0: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
dec0: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
ded0: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
dee0: 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
def0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
df00: 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
df10: 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
df20: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
df30: 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
df40: 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
df50: 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
df60: 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
df70: 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
df80: 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
df90: 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
dfa0: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
dfb0: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
dfc0: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
dfd0: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
dfe0: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
dff0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
e000: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
e010: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
e020: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
e030: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
e040: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
e050: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
e060: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
e070: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
e080: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
e090: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
e0a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
e0b0: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
e0c0: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
e0d0: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
e0e0: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
e0f0: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
e100: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
e110: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
e120: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
e130: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
e140: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
e150: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
e160: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
e170: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
e180: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
e190: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
e1a0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
e1b0: 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c   Thus, when call
e1c0: 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
e1d0: 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
e1e0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
e1f0: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
e200: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
e210: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
e220: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
e230: 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
e240: 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
e250: 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68  top level.  With
e260: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
e270: 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
e280: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e290: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
e2a0: 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
e2b0: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
e2c0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
e2d0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
e2e0: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
e2f0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
e300: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
e310: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
e320: 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
e330: 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
e340: 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
e350: 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
e360: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
e370: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
e380: 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
e390: 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
e3a0: 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
e3b0: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
e3c0: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
e3d0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
e3e0: 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
e3f0: 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
e400: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
e410: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
e420: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
e430: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
e440: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
e450: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
e460: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
e470: 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65  s from the table
e480: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  .)  Because of t
e490: 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74  his.** optimizat
e4a0: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
e4b0: 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52  ns in "DELETE FR
e4c0: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f  OM table" are no
e4d0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e  t row changes an
e4e0: 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65  d.** will not be
e4f0: 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20   counted by the 
e500: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
e510: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f  ) or [sqlite3_to
e520: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a  tal_changes()].*
e530: 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67  * functions, reg
e540: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
e550: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
e560: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
e570: 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65  inally.** in the
e580: 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20   table.  To get 
e590: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
e5a0: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
e5b0: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
e5c0: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
e5d0: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
e5e0: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
e5f0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
e600: 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68  *.** {F12241} Th
e610: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
e620: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  es()] function s
e630: 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  hall return the 
e640: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
e650: 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65        row change
e660: 73 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20  s caused by the 
e670: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
e680: 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20  RT, UPDATE,.**  
e690: 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54          or DELET
e6a0: 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  E statement on t
e6b0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
e6c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a   connection and.
e6d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
e6e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68  in the same or h
e6f0: 69 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f  igher trigger co
e700: 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69  ntext, or zero i
e710: 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20  f there have.** 
e720: 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65           not bee
e730: 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67  n any qualifying
e740: 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a   row changes..**
e750: 0a 2a 2a 20 7b 46 31 32 32 34 33 7d 20 53 74 61  .** {F12243} Sta
e760: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
e770: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
e780: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
e790: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
e7a0: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
e7b0: 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75  ll cause subsequ
e7c0: 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
e7d0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
e7e0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20  3_changes()] to 
e7f0: 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67  return zero, reg
e800: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a  ardless of the.*
e810: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
e820: 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e  r of rows origin
e830: 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c  ally in the tabl
e840: 65 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  e..**.** LIMITAT
e850: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
e860: 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  252} If a separa
e870: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
e880: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
e890: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
e8a0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
e8b0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
e8c0: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
e8d0: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
e8e0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e8f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
e900: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
e910: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
e920: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
e930: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
e940: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
e950: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
e960: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
e970: 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 0a 2a  ed {F12260}.**.*
e980: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
e990: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
e9a0: 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
e9b0: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
e9c0: 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72  RT,.** UPDATE or
e9d0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
e9e0: 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
e9f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea00: 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
ea10: 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c  * The count incl
ea20: 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
ea30: 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65   from all trigge
ea40: 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77  r contexts.  How
ea50: 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
ea60: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
ea70: 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
ea80: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45   to implement RE
ea90: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
eaa0: 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
eab0: 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
eac0: 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20  essing, or DROP 
ead0: 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67  table processing
eae0: 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73  ..** The changes
eaf0: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20   are counted as 
eb00: 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74  soon as the stat
eb10: 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
eb20: 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70   them is.** comp
eb30: 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
eb40: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
eb50: 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
eb60: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
eb70: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
eb80: 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
eb90: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
eba0: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
ebb0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
ebc0: 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
ebd0: 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
ebe0: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
ebf0: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
ec00: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
ec10: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
ec20: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
ec30: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
ec40: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
ec50: 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65  s from the table
ec60: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  .)  Because of t
ec70: 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74  his.** optimizat
ec80: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
ec90: 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52  ns in "DELETE FR
eca0: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f  OM table" are no
ecb0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e  t row changes an
ecc0: 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65  d.** will not be
ecd0: 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20   counted by the 
ece0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
ecf0: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f  ) or [sqlite3_to
ed00: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a  tal_changes()].*
ed10: 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67  * functions, reg
ed20: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
ed30: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
ed40: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
ed50: 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65  inally.** in the
ed60: 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20   table.  To get 
ed70: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
ed80: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
ed90: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
eda0: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
edb0: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
edc0: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
edd0: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
ede0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
edf0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
ee00: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
ee10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20  .**.** {F12261} 
ee20: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
ee30: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65  al_changes()] re
ee40: 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
ee50: 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
ee60: 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65     of row change
ee70: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
ee80: 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f  RT, UPDATE, and/
ee90: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20  or DELETE.**    
eea0: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
eeb0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
eec0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eed0: 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20  n], in any.**   
eee0: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
eef0: 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68  ontext, since th
ef00: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
ef10: 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65  ction was create
ef20: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 33  d..**.** {F12263
ef30: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
ef40: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
ef50: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
ef60: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
ef70: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
ef80: 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e  e shall not chan
ef90: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
efa0: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
efb0: 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f    by [sqlite3_to
efc0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a  tal_changes()]..
efd0: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
efe0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34  S:.**.** {A12264
eff0: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
f000: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
f010: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
f020: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f030: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
f040: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
f050: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
f060: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
f070: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
f080: 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
f090: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
f0a0: 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
f0b0: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
f0c0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
f0d0: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f0f0: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
f100: 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31  unning Query {F1
f110: 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2270}.**.** This
f120: 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
f130: 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
f140: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
f150: 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
f160: 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
f170: 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
f180: 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
f190: 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
f1a0: 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
f1b0: 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
f1c0: 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
f1d0: 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
f1e0: 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
f1f0: 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
f200: 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
f210: 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
f220: 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
f230: 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65  **.** It is safe
f240: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
f250: 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
f260: 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
f270: 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
f280: 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
f290: 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
f2a0: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
f2b0: 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
f2c0: 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
f2d0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
f2e0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
f2f0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
f300: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
f310: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
f320: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
f330: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
f340: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c  .**.** If an SQL
f350: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
f360: 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
f370: 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
f380: 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
f390: 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
f3a0: 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
f3b0: 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
f3c0: 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
f3d0: 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
f3e0: 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
f3f0: 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
f400: 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20  n..**.** An SQL 
f410: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
f420: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
f430: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
f440: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
f450: 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70   If the interrup
f460: 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
f470: 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
f480: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
f490: 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
f4a0: 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
f4b0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
f4c0: 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
f4d0: 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
f4e0: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
f4f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
f500: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f510: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
f520: 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  () has no effect
f530: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
f540: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
f550: 74 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c  tarted after sql
f560: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
f570: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
f580: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
f590: 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b  * {F12271} The [
f5a0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f5b0: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  t()] interface w
f5c0: 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75  ill force all ru
f5d0: 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
f5e0: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
f5f0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
f600: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
f610: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
f620: 20 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c            to hal
f630: 74 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69  t after processi
f640: 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61  ng at most one a
f650: 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66  dditional row of
f660: 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   data..**.** {F1
f670: 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74  2272} Any SQL st
f680: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20  atement that is 
f690: 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b  interrupted by [
f6a0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f6b0: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
f6c0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
f6d0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
f6e0: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
f6f0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37  NS:.**.** {A1227
f700: 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  9} If the databa
f710: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
f720: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
f730: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
f740: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
f750: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
f760: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
f770: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
f780: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
f790: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
f7a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f7b0: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
f7c0: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
f7d0: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30  Is Complete {F10
f7e0: 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  510}.**.** These
f7f0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
f800: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
f810: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
f820: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
f830: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
f840: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
f850: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
f860: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
f870: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
f880: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
f890: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
f8a0: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
f8b0: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
f8c0: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
f8d0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
f8e0: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
f8f0: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
f900: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
f910: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
f920: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
f930: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
f940: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
f950: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
f960: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
f970: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
f980: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
f990: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
f9a0: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
f9b0: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
f9c0: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
f9d0: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
f9e0: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
f9f0: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
fa00: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
fa10: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
fa20: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
fa30: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
fa40: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
fa50: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
fa60: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
fa70: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
fa80: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
fa90: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
faa0: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
fab0: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
fac0: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
fad0: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
fae0: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
faf0: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
fb00: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
fb10: 2a 20 7b 46 31 30 35 31 31 7d 20 41 20 73 75 63  * {F10511} A suc
fb20: 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69  cessful evaluati
fb30: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
fb40: 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a  omplete()] or.**
fb50: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
fb60: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
fb70: 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c   functions shall
fb80: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
fb90: 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20  urn a numeric 1 
fba0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
fbb0: 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74  he last non-whit
fbc0: 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  espace.**       
fbd0: 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69     token in thei
fbe0: 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d  r input is a sem
fbf0: 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e  icolon that is n
fc00: 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ot in between.**
fc10: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45            the BE
fc20: 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61  GIN and END of a
fc30: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
fc40: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
fc50: 20 7b 46 31 30 35 31 32 7d 20 49 66 20 61 20 6d   {F10512} If a m
fc60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fc70: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
fc80: 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69  ring an invocati
fc90: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
fca0: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
fcb0: 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ete()] or [sqlit
fcc0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
fcd0: 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
fce0: 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
fcf0: 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
fd00: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
fd10: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
fd20: 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65  .** {A10512} The
fd30: 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
fd40: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
fd50: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
fd60: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
fd70: 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
fd80: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33  g..**.** {A10513
fd90: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  } The input to [
fda0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
fdb0: 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
fdc0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
fdd0: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
fde0: 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
fdf0: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
fe00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
fe10: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
fe20: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
fe30: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
fe40: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
fe50: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
fe60: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
fe70: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
fe80: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
fe90: 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a  rors {F12310}.**
fea0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
feb0: 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
fec0: 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
fed0: 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
fee0: 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
fef0: 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
ff00: 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
ff10: 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
ff20: 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
ff30: 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
ff40: 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  cked..**.** If t
ff50: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
ff60: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
ff70: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
ff80: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
ff90: 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
ffa0: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
ffb0: 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
ffc0: 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66  ing the lock. If
ffd0: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
ffe0: 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
fff0: 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
10000 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
10010 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
10020 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
10030 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10040 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72  t to the handler
10050 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
10060 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
10070 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
10080 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
10090 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
100a0 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73  andler().  The s
100b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
100c0 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  o.** the handler
100d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
100e0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
100f0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
10100 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
10110 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
10120 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
10130 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  t.  If the.** bu
10140 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
10150 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
10160 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
10170 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
10180 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
10190 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
101a0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
101b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
101c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
101d0 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
101e0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
101f0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
10200 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
10210 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
10220 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
10230 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
10240 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
10250 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
10260 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
10270 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
10280 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
10290 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
102a0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
102b0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66  k contention. If
102c0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
102d0 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
102e0 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
102f0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
10300 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
10310 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
10320 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
10330 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
10340 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
10350 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
10360 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
10370 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
10380 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
10390 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
103a0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
103b0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
103c0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
103d0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
103e0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
103f0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
10400 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
10410 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
10420 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
10430 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
10440 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
10450 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
10460 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
10470 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
10480 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
10490 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
104a0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
104b0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
104c0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
104d0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
104e0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
104f0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
10500 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
10510 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
10520 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
10530 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
10540 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
10550 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
10560 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
10570 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
10580 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
10590 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
105a0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
105b0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
105c0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
105d0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
105e0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
105f0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
10600 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
10610 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
10620 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  L..**.** The [SQ
10630 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
10640 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
10650 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
10660 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
10670 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
10680 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
10690 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
106a0 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
106b0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
106c0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
106d0 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
106e0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
106f0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
10700 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
10710 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
10720 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
10730 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
10740 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
10750 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
10760 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
10770 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
10780 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
10790 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
107a0 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
107b0 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20  ders.  If it is 
107c0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
107d0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
107e0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
107f0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
10800 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
10810 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
10820 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
10830 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
10840 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
10850 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
10860 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
10870 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
10880 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
10890 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20  BLOCKED].  This 
108a0 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
108b0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
108c0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
108d0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
108e0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
108f0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
10900 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
10910 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
10920 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
10930 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
10940 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
10950 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
10960 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
10970 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
10980 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ant..**.** There
10990 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
109a0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
109b0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
109c0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
109d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
109e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
109f0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
10a00 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
10a10 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20  ly set handler. 
10a20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
10a30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
10a40 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
10a50 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
10a60 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
10a70 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e  andler..**.** IN
10a80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
10a90 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71  {F12311} The [sq
10aa0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10ab0 65 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74  er(D,C,A)] funct
10ac0 69 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63  ion shall replac
10ad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  e.**          bu
10ae0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74  sy callback in t
10af0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10b00 6e 65 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20  nection] D with 
10b10 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
10b20 20 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e    a new busy han
10b30 64 6c 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69  dler C and appli
10b40 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
10b50 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ter A..**.** {F1
10b60 32 33 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61  2312} Newly crea
10b70 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ted [database co
10b80 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c  nnections] shall
10b90 20 68 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20   have a busy.** 
10ba0 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72           handler
10bb0 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   of NULL..**.** 
10bc0 7b 46 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77  {F12314} When tw
10bd0 6f 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62  o or more [datab
10be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10bf0 20 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20   share a.**     
10c00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e       [sqlite3_en
10c10 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
10c20 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65  e | common cache
10c30 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
10c40 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
10c50 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
10c60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72   connection curr
10c70 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20  ently using.**  
10c80 20 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68          the cach
10c90 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b  e shall be invok
10ca0 65 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68  ed when the cach
10cb0 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c  e encounters a l
10cc0 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ock..**.** {F123
10cd0 31 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61  16} If a busy ha
10ce0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  ndler callback r
10cf0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
10d00 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10d10 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
10d20 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64     that provoked
10d30 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65   the locking eve
10d40 6e 74 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  nt shall return 
10d50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
10d60 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51  *.** {F12318} SQ
10d70 4c 69 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  Lite shall invok
10d80 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
10d90 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67  ler with two arg
10da0 75 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20  uments which.** 
10db0 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63           are a c
10dc0 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74  opy of the point
10dd0 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  er supplied by t
10de0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
10df0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
10e00 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10e10 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63  ndler()] and a c
10e20 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
10e30 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20  er of prior.**  
10e40 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
10e50 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20  ons of the busy 
10e60 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
10e70 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
10e80 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  nt..**.** LIMITA
10e90 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
10ea0 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e  2319} A busy han
10eb0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
10ec0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
10ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
10ee0 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70          or [prep
10ef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
10f00 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
10f10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
10f20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
10f30 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
10f40 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
10f50 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
10f60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10f70 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
10f80 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a  out {F12340}.**.
10f90 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10fa0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
10fb0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
10fc0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
10fd0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
10fe0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
10ff0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
11000 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
11010 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
11020 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
11030 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
11040 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
11050 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
11060 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
11070 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
11080 46 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  F12343} After "m
11090 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
110a0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
110b0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
110c0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
110d0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
110e0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
110f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
11100 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
11110 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
11120 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
11130 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
11140 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
11150 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
11160 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
11170 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
11180 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
11190 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
111a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
111b0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
111c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
111d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
111e0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
111f0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
11200 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
11210 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
11220 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
11230 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
11240 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
11250 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
11260 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
11270 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
11280 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
11290 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20  .**.** {F12341} 
112a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  The [sqlite3_bus
112b0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e  y_timeout()] fun
112c0 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72  ction shall over
112d0 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a  ride any prior.*
112e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
112f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11300 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
11310 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20  busy_handler()] 
11320 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20  setting.**      
11330 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20      on the same 
11340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11350 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tion]..**.** {F1
11360 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64  2343} If the 2nd
11370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
11380 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
11390 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74  out()] is less t
113a0 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
113b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
113c0 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20  , then the busy 
113d0 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65  handler shall be
113e0 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74   cleared so that
113f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
11400 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b   subsequent lock
11410 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64  ing events immed
11420 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53  iately return [S
11430 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
11440 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20 74  ** {F12344} If t
11450 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
11460 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
11470 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
11480 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20  a positive.**   
11490 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c         number N,
114a0 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e   then a busy han
114b0 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65  dler shall be se
114c0 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c  t that repeatedl
114d0 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20  y calls.**      
114e0 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29      the xSleep()
114f0 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b   method in the [
11500 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
11510 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74  S interface] unt
11520 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  il.**          e
11530 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63  ither the lock c
11540 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74  lears or until t
11550 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c  he cumulative sl
11560 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20  eep time.**     
11570 20 20 20 20 20 72 65 70 6f 72 74 65 64 20 62 61       reported ba
11580 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20 65  ck by xSleep() e
11590 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65  xceeds N millise
115a0 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  conds..*/.int sq
115b0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
115c0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
115d0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
115e0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
115f0 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
11600 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20  Running Queries 
11610 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44  {F12370}.**.** D
11620 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
11630 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
11640 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
11650 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
11660 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
11670 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11680 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
11690 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
116a0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
116b0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
116c0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
116d0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
116e0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
116f0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
11700 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
11710 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
11720 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
11730 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
11740 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
11750 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
11760 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
11770 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
11780 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
11790 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
117a0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
117b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
117c0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
117d0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
117e0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
117f0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
11800 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
11810 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
11820 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
11830 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
11840 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
11850 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
11860 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11870 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
11880 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
11890 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
118a0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
118b0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
118c0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
118d0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
118e0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
118f0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
11900 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
11910 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
11920 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
11930 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
11940 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
11950 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
11960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
11970 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
11980 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
11990 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
119a0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
119b0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
119c0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
119d0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
119e0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
119f0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
11a00 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
11a10 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
11a20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
11a30 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
11a40 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
11a50 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
11a60 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
11a70 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
11a80 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
11a90 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
11aa0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
11ab0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
11ac0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
11ad0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
11ae0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
11af0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
11b00 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
11b10 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
11b20 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
11b30 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
11b40 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
11b50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11b60 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
11b70 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
11b80 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
11b90 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
11ba0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
11bb0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
11bc0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
11bd0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
11be0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
11bf0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
11c00 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
11c10 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
11c20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
11c30 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
11c40 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11c50 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
11c60 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
11c70 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
11c80 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
11c90 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
11ca0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
11cb0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11cc0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
11cd0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11ce0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
11cf0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11d00 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
11d10 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
11d20 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
11d30 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
11d40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11d50 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
11d60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
11d70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
11d80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
11d90 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
11da0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
11db0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
11dc0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
11dd0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
11de0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
11df0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
11e00 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
11e10 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
11e20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
11e30 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
11e40 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
11e50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
11e60 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
11e70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
11e80 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
11e90 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
11ea0 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
11eb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
11ec0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
11ed0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11ee0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
11ef0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
11f00 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
11f10 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
11f20 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
11f30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
11f40 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
11f50 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
11f60 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
11f70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
11f80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
11f90 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
11fa0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
11fb0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
11fc0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
11fd0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
11fe0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
11ff0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
12000 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
12010 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12020 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
12030 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
12040 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
12050 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
12060 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
12070 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12080 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
12090 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
120a0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
120b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
120c0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
120d0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
120e0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
120f0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
12100 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
12110 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
12120 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
12130 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
12140 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
12150 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
12160 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
12170 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
12180 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
12190 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
121a0 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
121b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
121c0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
121d0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31  S:.**.** {F12371
121e0 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
121f0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
12200 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
12210 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
12220 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c           it shal
12230 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c  l free the resul
12240 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
12250 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
12260 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
12270 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65    query in proce
12280 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62  ss, skip any sub
12290 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
122a0 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   set the.**     
122b0 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20       *pazResult 
122c0 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74  output pointer t
122d0 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72  o NULL and retur
122e0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
122f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d  ..**.** {F12373}
12300 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e   If the pnColumn
12310 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
12320 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12330 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
12340 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
12350 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
12360 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
12370 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12380 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
12390 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75      write the nu
123a0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
123b0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
123c0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
123d0 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
123e0 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  *pnColumn..**.**
123f0 20 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68 65   {F12374} If the
12400 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72   pnRow parameter
12410 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
12420 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
12430 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
12440 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
12450 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
12460 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
12470 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
12480 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73            writes
12490 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
124a0 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
124b0 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
124c0 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
124d0 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a  nto *pnRow..**.*
124e0 2a 20 7b 46 31 32 33 37 36 7d 20 41 20 73 75 63  * {F12376} A suc
124f0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
12500 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
12510 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74  et_table()] that
12520 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20   computes.**    
12530 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20        N rows of 
12540 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f  result with C co
12550 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68  lumns per row sh
12560 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73  all make *pazRes
12570 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ult.**          
12580 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61  point to an arra
12590 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
125a0 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73   (N+1)*C strings
125b0 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
125c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73  .**          C s
125d0 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d  trings are colum
125e0 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69  n names as obtai
125f0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ned from.**     
12600 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
12610 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
12620 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f   the rest are co
12630 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75  lumn result valu
12640 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
12650 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
12660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
12670 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  t()]..**.** {F12
12680 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20  379} The values 
12690 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74  in the pazResult
126a0 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20   array returned 
126b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  by [sqlite3_get_
126c0 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  table()].**     
126d0 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69       shall remai
126e0 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c  n valid until cl
126f0 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eared by [sqlite
12700 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
12710 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 38 32 7d 20  .**.** {F12382} 
12720 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
12730 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c  curs during eval
12740 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
12750 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
12760 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12770 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73  function shall s
12780 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f  et *pazResult to
12790 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20   NULL, write an 
127a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
127b0 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d            into m
127c0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
127d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
127e0 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20  loc()], make.** 
127f0 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72           **pzErr
12800 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61  msg point to tha
12810 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c  t error message,
12820 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a   and return a.**
12830 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
12840 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
12850 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
12860 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
12870 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
12880 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
12890 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
128a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
128b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
128c0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
128d0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
128e0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
128f0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
12900 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
12910 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
12920 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
12930 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
12940 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
12950 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
12960 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
12970 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
12980 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
12990 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
129a0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
129b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
129c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
129d0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
129e0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
129f0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
12a00 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
12a10 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37  g Functions {F17
12a20 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
12a30 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
12a40 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
12a50 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
12a60 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
12a70 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
12a80 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
12a90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12aa0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
12ab0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
12ac0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
12ad0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
12ae0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
12af0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
12b00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
12b10 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
12b20 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
12b30 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
12b40 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
12b50 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
12b60 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72  free()].  Both r
12b70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
12b80 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
12b90 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
12ba0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
12bb0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
12bc0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
12bd0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
12be0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
12bf0 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
12c00 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
12c10 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
12c20 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
12c30 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
12c40 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
12c50 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
12c60 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
12c70 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
12c80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
12c90 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
12ca0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
12cb0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12cc0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
12cd0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
12ce0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
12cf0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
12d00 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
12d10 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e  f().  This is an
12d20 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
12d30 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
12d40 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
12d50 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
12d60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
12d70 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20  tibility.  Note 
12d80 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
12d90 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12da0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
12db0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
12dc0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
12dd0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
12de0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
12df0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
12e00 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d   buffer.  We adm
12e10 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
12e20 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
12e30 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
12e40 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
12e50 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
12e60 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
12e70 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
12e80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
12e90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12ea0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
12eb0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
12ec0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73  bility..**.** As
12ed0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
12ee0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
12ef0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
12f00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
12f10 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
12f20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
12f30 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
12f40 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
12f50 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
12f60 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
12f70 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
12f80 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
12f90 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
12fa0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
12fb0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
12fc0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
12fd0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
12fe0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
12ff0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
13000 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
13010 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
13020 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
13030 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
13040 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
13050 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
13060 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
13070 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
13080 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
13090 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
130a0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
130b0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
130c0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
130d0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
130e0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
130f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f  ..**.** The %q o
13100 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
13110 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
13120 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
13130 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
13140 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
13150 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
13160 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
13170 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
13180 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
13190 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
131a0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
131b0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79  ing literal.  By
131c0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
131d0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
131e0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
131f0 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
13200 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
13210 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
13220 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
13230 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
13240 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
13250 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
13260 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
13270 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
13280 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13290 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
132a0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
132b0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
132c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
132d0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
132e0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
132f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
13300 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
13310 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13320 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
13330 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
13340 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
13350 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
13360 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
13370 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
13380 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
13390 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
133a0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
133b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
133c0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
133d0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
133e0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
133f0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
13400 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
13410 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
13420 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
13430 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
13440 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13450 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
13460 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
13470 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
13480 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
13490 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
134a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
134b0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
134c0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
134d0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
134e0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
134f0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
13500 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
13510 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
13520 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
13530 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
13540 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
13550 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
13560 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13570 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
13580 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
13590 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
135a0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
135b0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
135c0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
135d0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
135e0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
135f0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
13600 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
13610 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
13620 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
13630 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
13640 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
13650 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
13660 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
13670 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
13680 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
13690 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
136a0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
136b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
136c0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
136d0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
136e0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
136f0 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61  e quotes) in pla
13700 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74  ce of the %Q opt
13710 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ion.  So, for ex
13720 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
13730 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
13740 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13750 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
13760 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
13770 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
13780 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
13790 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
137a0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
137b0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
137c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
137d0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
137e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
137f0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
13800 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
13810 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
13820 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
13830 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
13840 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
13850 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
13860 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
13870 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
13880 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
13890 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25   exactly like "%
138a0 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  s" with the.** a
138b0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
138c0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
138d0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
138e0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
138f0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
13900 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
13910 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
13920 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d  ut string. {END}
13930 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
13940 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33  S:.**.** {F17403
13950 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
13960 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b  mprintf()] and [
13970 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13980 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
13990 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
139a0 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65  rn either pointe
139b0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
139c0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
139d0 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20  ngs held in.**  
139e0 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
139f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
13a00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13a10 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   or NULL pointer
13a20 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s if.**         
13a30 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    a call to [sql
13a40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
13a50 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ails..**.** {F17
13a60 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  406}  The [sqlit
13a70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
13a80 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
13a90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
13aa0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55  d.**           U
13ab0 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f  TF-8 string into
13ac0 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e   the buffer poin
13ad0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65  ted to by the se
13ae0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
13af0 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76  *           prov
13b00 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69  ided that the fi
13b10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
13b20 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
13b30 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30  ro..**.** {F1740
13b40 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  7}  The [sqlite3
13b50 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
13b60 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
13b70 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a  write slots of.*
13b80 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
13b90 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
13ba0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13bb0 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
13bc0 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
13bd0 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
13be0 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
13bf0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13c00 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
13c10 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
13c20 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
13c30 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
13c40 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
13c50 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
13c60 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f  pecification..*/
13c70 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
13c80 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
13c90 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
13ca0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
13cb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
13cc0 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
13cd0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
13ce0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
13cf0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
13d00 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
13d10 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
13d20 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d  bsystem {F17300}
13d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
13d40 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65  e core  uses the
13d50 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
13d60 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
13d70 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
13d80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13d90 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
13da0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
13db0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
13dc0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
13dd0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
13de0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
13df0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
13e00 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
13e10 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
13e20 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
13e30 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
13e40 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ons..**.** The s
13e50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13e60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
13e70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
13e80 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
13e90 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
13ea0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
13eb0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
13ec0 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71  ameter..** If sq
13ed0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
13ee0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
13ef0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
13f00 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
13f10 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
13f20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65  pointer.  If the
13f30 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
13f40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
13f50 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
13f60 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
13f70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
13f80 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
13f90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43  pointer..**.** C
13fa0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
13fb0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
13fc0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
13fd0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
13fe0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13ff0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
14000 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
14010 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
14020 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
14030 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71   reused.  The sq
14040 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
14050 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
14060 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
14070 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
14080 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
14090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
140a0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
140b0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
140c0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
140d0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
140e0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
140f0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
14100 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
14110 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
14120 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
14130 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
14140 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
14150 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
14160 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
14170 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
14180 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
14190 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
141a0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
141b0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
141c0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
141d0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
141e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
141f0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
14200 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
14210 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
14220 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a  lite3_free()..**
14230 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14240 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
14250 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
14260 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
14270 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
14280 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
14290 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
142a0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
142b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
142c0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
142d0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
142e0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
142f0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
14300 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
14310 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14320 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
14330 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
14340 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
14350 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
14360 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
14370 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
14380 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
14390 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
143a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
143b0 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
143c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
143d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
143e0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
143f0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
14400 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
14410 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
14420 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
14430 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
14440 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
14450 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14460 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
14470 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
14480 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
14490 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
144a0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
144b0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
144c0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
144d0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
144e0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
144f0 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
14500 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
14510 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
14520 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
14530 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
14540 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
14550 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
14560 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
14570 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
14580 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
14590 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
145a0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
145b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
145c0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
145d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
145e0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
145f0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
14600 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
14610 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
14620 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
14630 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
14640 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
14650 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
14660 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
14670 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
14680 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
14690 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
146a0 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
146b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
146c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
146d0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
146e0 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
146f0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
14700 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
14710 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
14720 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
14730 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  F17382} However,
14740 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
14750 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14760 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
14770 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
14780 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
14790 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
147a0 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
147b0 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
147c0 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
147d0 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
147e0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
147f0 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
14800 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
14810 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
14820 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
14830 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14840 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
14850 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
14860 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
14870 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
14880 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
14890 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
148a0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
148b0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
148c0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
148d0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
148e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
148f0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
14900 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
14910 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
14920 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
14930 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
14940 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
14950 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
14960 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
14970 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
14980 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
14990 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
149a0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
149b0 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
149c0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
149d0 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
149e0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
149f0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
14a00 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
14a10 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
14a20 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
14a30 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
14a40 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
14a50 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
14a60 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
14a70 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
14a80 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
14a90 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
14aa0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
14ab0 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
14ac0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
14ad0 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
14ae0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
14af0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
14b00 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
14b10 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
14b20 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
14b30 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14b40 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68  .** {F17303}  Th
14b50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
14b60 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
14b70 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
14b80 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
14b90 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79           a newly
14ba0 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f   checked-out blo
14bb0 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ck of at least N
14bc0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
14bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
14be0 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
14bf0 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75  gned, or it retu
14c00 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69  rns NULL if it i
14c10 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20  s unable.**     
14c20 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c        to fulfill
14c30 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a   the request..**
14c40 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68  .** {F17304}  Th
14c50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
14c60 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
14c70 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
14c80 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20  ointer if.**    
14c90 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73         N is less
14ca0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
14cb0 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o zero..**.** {F
14cc0 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c  17305}  The [sql
14cd0 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e  ite3_free(P)] in
14ce0 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73  terface releases
14cf0 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73   memory previous
14d00 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
14d10 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
14d20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14d30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
14d40 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
14d50 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20        making it 
14d60 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65  available for re
14d70 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  use..**.** {F173
14d80 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  06}  A call to [
14d90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c  sqlite3_free(NUL
14da0 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73  L)] is a harmles
14db0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b  s no-op..**.** {
14dc0 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20  F17310}  A call 
14dd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
14de0 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75  loc(0,N)] is equ
14df0 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
14e00 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
14e10 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
14e20 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  c(N)]..**.** {F1
14e30 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7312}  A call to
14e40 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14e50 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76  c(P,0)] is equiv
14e60 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
14e70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
14e80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
14e90 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35  ]..**.** {F17315
14ea0 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  }  The SQLite co
14eb0 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33  re uses [sqlite3
14ec0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
14ed0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
14ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e  .**           an
14ef0 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  d [sqlite3_free(
14f00 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  )] for all of it
14f10 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14f20 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
14f30 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f       deallocatio
14f40 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  n needs..**.** {
14f50 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71  F17318}  The [sq
14f60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
14f70 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
14f80 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
14f90 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
14fa0 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f      to a block o
14fb0 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65  f checked-out me
14fc0 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
14fd0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
14fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
14ff0 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
15000 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20  gned, or a NULL 
15010 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
15020 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73  F17321}  When [s
15030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
15040 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
15050 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
15060 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
15070 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68         copies th
15080 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20  e first K bytes 
15090 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20  of content from 
150a0 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79  P into the newly
150b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c  .**           al
150c0 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77  located block, w
150d0 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65  here K is the le
150e0 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68  sser of N and th
150f0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20  e size of.**    
15100 20 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65         the buffe
15110 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  r P..**.** {F173
15120 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  22}  When [sqlit
15130 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
15140 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e   returns a non-N
15150 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20  ULL pointer, it 
15160 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
15170 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20     releases the 
15180 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
15190 7b 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b  {F17323}  When [
151a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
151b0 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55  P,N)] returns NU
151c0 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50  LL, the buffer P
151d0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
151e0 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72   not modified or
151f0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
15200 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
15210 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68  .** {A17350}  Th
15220 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
15230 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
15240 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
15250 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
15260 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73  **           mus
15270 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
15280 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
15290 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
152a0 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  a prior.**      
152b0 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20       invocation 
152c0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
152d0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
152e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
152f0 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  t have.**       
15300 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e      not yet been
15310 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
15320 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20 61   {A17351}  The a
15330 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15340 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
15350 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
15360 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f             a blo
15370 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
15380 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
15390 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
153a0 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
153b0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
153c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
153d0 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
153e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
153f0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
15400 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
15410 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
15420 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
15430 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15440 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
15450 20 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37   Statistics {F17
15460 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  370}.**.** SQLit
15470 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
15480 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
15490 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
154a0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
154b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
154c0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
154d0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
154e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
154f0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
15500 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
15510 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
15520 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
15530 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  stem..**.** INVA
15540 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
15550 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  17371} The [sqli
15560 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15570 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
15580 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
15590 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
155a0 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72     of memory cur
155b0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
155c0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
155d0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a   not freed)..**.
155e0 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20  ** {F17373} The 
155f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15600 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
15610 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
15620 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20   maximum.**     
15630 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73       value of [s
15640 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
15650 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
15660 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
15670 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20  **          was 
15680 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a  last reset..**.*
15690 2a 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76  * {F17374} The v
156a0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
156b0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
156c0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
156d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
156e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
156f0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
15700 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20  ny overhead.**  
15710 20 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79          added by
15720 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
15730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15750 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
15760 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
15770 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
15780 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
15790 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
157a0 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
157b0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
157c0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
157d0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  ll..**.** {F1737
157e0 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  5} The memory hi
157f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
15800 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
15810 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
15820 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
15830 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15840 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
15850 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15860 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
15870 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
15880 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
15890 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20  rue.  The value 
158a0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
158b0 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
158c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
158d0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
158e0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
158f0 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74           prior t
15900 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
15910 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
15920 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15930 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
15940 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
15950 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
15960 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
15970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15980 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
15990 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
159a0 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53  {F17390}.**.** S
159b0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
159c0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
159d0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
159e0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
159f0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
15a00 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57  elect random ROW
15a10 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69  IDs when inserti
15a20 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
15a30 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
15a40 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
15a50 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
15a60 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68  sible ROWID.  Th
15a70 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
15a80 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
15a90 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
15aa0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
15ab0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
15ac0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
15ad0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
15ae0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
15af0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
15b00 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
15b10 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
15b20 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
15b30 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
15b40 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
15b50 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
15b60 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
15b70 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
15b80 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
15b90 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
15ba0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
15bb0 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
15bc0 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
15bd0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
15be0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
15bf0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
15c00 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
15c10 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
15c20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
15c30 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
15c40 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
15c50 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
15c60 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
15c70 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
15c80 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
15c90 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15ca0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
15cb0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
15cc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
15cd0 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65  .** {F17392} The
15ce0 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
15cf0 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
15d00 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
15d10 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
15d20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
15d30 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
15d40 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
15d50 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
15d60 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
15d70 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
15d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
15d90 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
15da0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
15db0 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a  ks {F12500}.**.*
15dc0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
15dd0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
15de0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
15df0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
15e00 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15e10 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
15e20 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
15e30 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
15e40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15e50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15e60 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
15e70 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
15e80 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
15e90 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
15ea0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
15eb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15ec0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15ed0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
15ee0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
15ef0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
15f00 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
15f10 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
15f20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
15f30 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
15f40 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
15f50 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
15f60 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
15f70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15f80 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15f90 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
15fa0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
15fb0 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
15fc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15fd0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
15fe0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
15ff0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
16000 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
16010 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
16020 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
16030 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
16040 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16050 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
16060 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
16070 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16080 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
16090 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
160a0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
160b0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
160c0 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75  rror.  If the au
160d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
160e0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
160f0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
16100 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
16110 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
16120 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16130 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
16140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16150 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16160 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
16170 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
16180 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
16190 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
161a0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
161b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
161c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
161d0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
161e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
161f0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
16200 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
16210 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16220 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
16230 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16240 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
16250 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
16260 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
16270 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
16280 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
16290 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
162a0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
162b0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
162c0 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
162d0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
162e0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
162f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
16300 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16310 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
16320 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
16330 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
16340 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
16350 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
16360 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
16370 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
16380 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
16390 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
163a0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
163b0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
163c0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
163d0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
163e0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
163f0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
16400 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
16410 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
16420 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
16430 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
16440 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
16450 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
16460 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16470 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
16480 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
16490 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
164a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
164b0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
164c0 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
164d0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
164e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
164f0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
16500 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
16510 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
16520 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
16530 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
16540 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68  e authorized. Th
16550 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
16560 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
16570 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
16580 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
16590 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
165a0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
165b0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
165c0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
165d0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
165e0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ized..**.** An a
165f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
16600 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
16610 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
16620 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
16630 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
16640 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
16650 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
16660 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
16670 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
16680 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
16690 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
166a0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
166b0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
166c0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
166d0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
166e0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
166f0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
16700 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
16710 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
16720 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
16730 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
16740 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
16750 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
16760 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
16770 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
16780 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
16790 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
167a0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
167b0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
167c0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
167d0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
167e0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
167f0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
16800 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
16810 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
16820 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
16830 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
16840 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
16850 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
16860 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
16870 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
16880 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
16890 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
168a0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
168b0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
168c0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
168d0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
168e0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
168f0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
16900 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
16910 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
16920 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
16930 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
16940 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
16950 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
16960 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
16970 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  izer..**.** Only
16980 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
16990 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
169a0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
169b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
169c0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
169d0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
169e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
169f0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
16a00 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
16a10 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
16a20 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
16a30 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
16a40 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
16a50 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
16a60 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
16a70 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
16a80 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
16a90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16aa0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
16ab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16ac0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
16ad0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
16ae0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
16af0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
16b00 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
16b10 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
16b20 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
16b30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
16b40 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68  *.** {F12501} Th
16b50 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
16b60 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
16b70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
16b80 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
16b90 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
16ba0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
16bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16bc0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30   D..**.** {F1250
16bd0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
16be0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
16bf0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
16c00 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
16c10 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f          being co
16c20 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  mpiled..**.** {F
16c30 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
16c40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16c50 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
16c60 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
16c70 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
16c80 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
16c90 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
16ca0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a  ITE_DENY], then.
16cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
16cc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16cd0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
16ce0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
16cf0 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
16d00 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
16d10 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
16d20 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
16d30 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
16d40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
16d50 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
16d60 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
16d70 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
16d80 2a 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20  * {F12504} When 
16d90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16da0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16db0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
16dc0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
16dd0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
16de0 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
16df0 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rmally..**.** {F
16e00 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
16e10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16e20 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
16e30 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
16e40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16e50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16e60 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
16e70 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
16e80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
16e90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16ea0 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
16eb0 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
16ec0 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
16ed0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
16ee0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
16ef0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
16f00 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
16f10 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
16f20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  denied..**.** {F
16f30 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
16f40 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
16f50 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
16f60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16f70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
16f80 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
16f90 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
16fa0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16fb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
16fc0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
16fd0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
16fe0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
16ff0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
17000 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
17010 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
17020 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
17030 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
17040 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
17050 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
17060 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
17070 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
17080 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
17090 0a 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20  .** {F12507} If 
170a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
170b0 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
170c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
170d0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
170e0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
170f0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
17100 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
17110 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
17120 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
17130 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
17140 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
17150 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
17160 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DENY]..**.** {F
17170 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
17180 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17190 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
171a0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
171b0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
171c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
171d0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
171e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
171f0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
17200 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54  **.** {F12511} T
17210 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17220 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
17230 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17240 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
17250 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
17260 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17270 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
17280 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
17290 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
172a0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
172b0 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20  ** {F12512} The 
172c0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
172d0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
172e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
172f0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
17300 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
17310 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
17320 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
17330 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
17340 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
17350 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17360 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
17370 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
17380 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
17390 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
173a0 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
173b0 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
173c0 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
173d0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orizer..**.** {F
173e0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
173f0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
17400 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
17410 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
17420 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17430 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
17440 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
17450 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
17460 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
17470 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17480 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
17490 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
174a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
174b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
174c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
174d0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
174e0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
174f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17500 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
17510 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30  rn Codes {F12590
17520 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  }.**.** The [sql
17530 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17540 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
17550 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17560 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
17570 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
17580 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
17590 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
175a0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
175b0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
175c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
175d0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
175e0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
175f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
17600 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
17610 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
17620 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
17630 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
17640 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69  mation..*/.#defi
17650 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
17660 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
17670 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17680 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
17690 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
176a0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
176b0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
176c0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
176d0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
176e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
176f0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
17700 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35  ion Codes {F1255
17710 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0}.**.** The [sq
17720 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17730 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
17740 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
17750 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
17760 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
17770 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
17780 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
17790 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
177a0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
177b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
177c0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
177d0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
177e0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
177f0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
17800 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
17810 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
17820 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
17830 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
17840 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17850 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
17860 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
17870 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
17880 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
17890 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
178a0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
178b0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
178c0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
178d0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
178e0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
178f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
17900 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
17910 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
17920 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
17930 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
17940 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
17950 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
17960 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
17970 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
17980 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
17990 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
179a0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
179b0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
179c0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
179d0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
179e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
179f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17a00 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
17a10 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
17a20 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
17a30 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
17a40 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
17a50 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
17a60 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
17a70 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
17a80 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
17a90 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
17aa0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
17ab0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
17ac0 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {F12551} The sec
17ad0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17ae0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
17af0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17b00 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17b10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
17b20 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65  s always an inte
17b30 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
17b40 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17b50 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
17b60 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77  that specifies w
17b70 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  hat action.**   
17b80 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20         is being 
17b90 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
17ba0 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33  * {F12552} The 3
17bb0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
17bc0 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  eters to the.** 
17bd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
17be0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17bf0 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e   | authorization
17c00 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20   callback].**   
17c10 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70         will be p
17c20 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
17c30 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
17c40 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
17c50 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
17c60 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
17c70 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
17c80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d  ..**.** {F12553}
17ca0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
17cb0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
17cc0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
17cd0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
17ce0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17cf0 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
17d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
17d10 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78  the database (ex
17d20 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22  ample: "main", "
17d30 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20  temp", etc.) if 
17d40 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a  applicable..**.*
17d50 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36  * {F12554} The 6
17d60 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
17d70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
17d80 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17d90 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17da0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
17db0 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
17dc0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
17dd0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
17de0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
17df0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
17e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
17e10 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
17e20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
17e30 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
17e40 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
17e50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d  **          top-
17e60 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
17e70 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
17e80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17e90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
17ea0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
17eb0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
17ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17ed0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
17ee0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
17ef0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
17f00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f20 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
17f30 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
17f40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17f50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17f70 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
17f80 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
17f90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
17fa0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17fc0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
17fd0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
17fe0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
17ff0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18010 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
18020 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
18030 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18040 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18060 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
18070 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
18080 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18090 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
180a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
180b0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
180c0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
180d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
180e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
180f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18100 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
18110 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
18120 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18130 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18140 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
18150 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
18160 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18170 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18190 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
181a0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
181b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
181c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
181d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
181e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
181f0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
18200 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18210 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18230 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
18240 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
18250 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18260 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18280 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
18290 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
182a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
182b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
182c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
182d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
182e0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
182f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18300 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18320 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
18330 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
18340 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18350 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18370 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
18380 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
18390 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
183a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
183b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
183c0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
183d0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
183e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
183f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18410 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
18420 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
18430 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18440 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
18460 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
18470 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
18480 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
18490 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
184a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
184b0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
184c0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
184d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
184e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
184f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
18500 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
18510 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
18520 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
18530 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18540 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
18550 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
18560 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
18570 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
18580 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18590 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
185a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
185b0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
185c0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
185d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
185e0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
185f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18600 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
18610 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18620 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18630 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
18640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
18650 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
18660 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
18670 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18680 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
18690 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
186a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
186b0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
186c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
186d0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
186e0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
186f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18700 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18720 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
18730 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
18740 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18750 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18770 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
18780 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
18790 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
187a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
187b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
187c0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
187d0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
187e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
187f0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
18800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18810 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
18820 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
18830 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
18840 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18860 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
18870 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
18880 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
18890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
188a0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
188b0 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
188c0 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a  s {F12280}.**.**
188d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
188e0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
188f0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
18900 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
18910 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
18920 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
18930 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
18940 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
18950 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
18960 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18970 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
18980 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
18990 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
189a0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
189b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
189c0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
189d0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54  e3_step()]..** T
189e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
189f0 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64  rns a UTF-8 rend
18a00 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c  ering of the SQL
18a10 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a   statement text.
18a20 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  ** as the statem
18a30 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
18a40 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64   executing.  Add
18a50 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  itional callback
18a60 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  s occur.** as ea
18a70 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
18a80 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
18a90 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
18aa0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
18ab0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
18ac0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
18ad0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
18ae0 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  he trigger..**.*
18af0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
18b00 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
18b10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
18b20 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
18b30 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
18b40 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
18b50 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69  shes.  The profi
18b60 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
18b70 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
18b80 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
18b90 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
18ba0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
18bb0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
18bc0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
18bd0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
18be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
18bf0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50  te3_profile() AP
18c00 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  I is currently c
18c10 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
18c20 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73  mental and.** is
18c30 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
18c40 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e  ge or removal in
18c50 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
18c60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69  e..**.** The tri
18c70 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66  gger reporting f
18c80 65 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72  eature of the tr
18c90 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
18ca0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78  considered.** ex
18cb0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
18cc0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
18cd0 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69  nge or removal i
18ce0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
18cf0 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72  s..** Future ver
18d00 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
18d10 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e  might also add n
18d20 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ew trace callbac
18d30 6b 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  k.** invocations
18d40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18d50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  TS:.**.** {F1228
18d60 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
18d70 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
18d80 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
18d90 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20  trace()] is.**  
18da0 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
18db0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18dc0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  t first begins t
18dd0 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a  o execute and.**
18de0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
18df0 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62  er a trigger sub
18e00 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65  program first be
18e10 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  gins to run..**.
18e20 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68  ** {F12282} Each
18e30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
18e40 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72  3_trace()] overr
18e50 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ides the previou
18e60 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
18e70 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65  registered trace
18e80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
18e90 20 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c   {F12283} A NULL
18ea0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
18eb0 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67  disables tracing
18ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d  ..**.** {F12284}
18ed0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18ee0 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
18ef0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
18f00 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
18f10 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77     the pointer w
18f20 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64  hich was the 3rd
18f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
18f40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a  lite3_trace()]..
18f50 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54  **.** {F12285} T
18f60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18f70 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
18f80 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
18f90 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
18fa0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
18fb0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
18fc0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  g the original t
18fd0 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
18fe0 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
18ff0 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
19000 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69  assed into [sqli
19010 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19020 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
19030 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c   the equivalent,
19040 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
19050 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  nt indicating th
19060 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20  e beginning.**  
19070 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69          of a tri
19080 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
19090 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20  .**.** {F12287} 
190a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
190b0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
190c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   by [sqlite3_pro
190d0 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b  file()] is invok
190e0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ed.**          a
190f0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
19100 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
19110 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68  *.** {F12288} Th
19120 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19130 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
19140 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
19150 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
19160 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d     the 3rd param
19170 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
19180 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a  _profile()]..**.
19190 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20  ** {F12289} The 
191a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
191b0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
191c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
191d0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
191e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
191f0 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74  string that cont
19200 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  ains the complet
19210 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20  e text of.**    
19220 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74        the SQL st
19230 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
19240 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b  s processed by [
19250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19260 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
19270 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
19280 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ent..**.** {F122
19290 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61  90} The third pa
192a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
192b0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
192c0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a  is an estimate.*
192d0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
192e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
192f0 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d  seconds of wall-
19300 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69  clock time requi
19310 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  red to.**       
19320 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73     run the SQL s
19330 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74  tatement from st
19340 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a  art to finish..*
19350 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
19360 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
19370 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
19380 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
19390 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
193a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
193b0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
193c0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
193d0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
193e0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
193f0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19400 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
19410 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
19420 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a  s {F12910}.**.**
19430 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
19440 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
19450 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
19460 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
19470 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
19480 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
19490 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
194a0 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
194b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
194c0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
194d0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
194e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
194f0 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
19500 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
19510 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
19520 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
19530 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
19540 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
19550 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
19560 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
19570 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
19580 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
19590 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
195a0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
195b0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
195c0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
195d0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
195e0 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  GUI dialog box..
195f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
19600 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d  :.**.** {F12911}
19610 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
19620 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19630 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
19640 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a  gress_handler().
19650 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
19660 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
19670 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
19680 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
19690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
196a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
196b0 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68  *.** {F12912} Th
196c0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
196d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
196e0 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
196f0 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20  virtual.**      
19700 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f      machine opco
19710 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  des, where N is 
19720 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19730 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
19740 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
19750 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
19760 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65  ()] call that re
19770 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
19780 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
19790 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  k.  If N is less
197a0 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33   than 1, sqlite3
197b0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
197c0 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
197d0 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c  acts as if a NUL
197e0 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  L progress handl
197f0 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65 63  er had been spec
19800 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ified..**.** {F1
19810 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65  2913} The progre
19820 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65  ss callback itse
19830 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
19840 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   by the third.**
19850 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
19860 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
19870 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
19880 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d  ..**.** {F12914}
19890 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
198a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
198b0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
198c0 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  () is a.**      
198d0 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72      void pointer
198e0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70   passed to the p
198f0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
19900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
19910 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
19920 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  it is invoked..*
19930 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66  *.** {F12915} If
19940 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
19950 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75  te3_step()] resu
19960 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
19970 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20  n N opcodes.**  
19980 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65 78          being ex
19990 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65  ecuted, then the
199a0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
199b0 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
199c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ked..**.** {F129
199d0 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74  16} Every call t
199e0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
199f0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
19a00 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77  *          overw
19a10 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f  rites any previo
19a20 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20  usly registered 
19a30 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
19a40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d  ..**.** {F12917}
19a50 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
19a60 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
19a70 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
19a80 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
19a90 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
19aa0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
19ab0 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65   {F12918} If the
19ac0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19ad0 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
19ae0 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
19af0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
19b00 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
19b10 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
19b20 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
19b30 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
19b40 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
19b50 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
19b60 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
19b70 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
19b80 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19b90 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
19ba0 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
19bb0 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30  nnection {F12700
19bc0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
19bd0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
19be0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
19bf0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
19c00 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
19c10 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
19c20 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
19c30 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
19c40 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
19c50 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
19c60 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19c70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
19c80 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
19c90 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
19ca0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
19cb0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
19cc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19cd0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
19ce0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
19cf0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
19d00 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
19d10 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
19d20 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
19d30 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
19d40 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
19d50 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
19d60 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
19d70 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
19d80 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
19d90 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
19da0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
19db0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
19dc0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
19dd0 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
19de0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
19df0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
19e00 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
19e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
19e20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
19e30 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
19e40 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
19e50 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
19e60 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
19e70 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
19e80 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
19e90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
19ea0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
19eb0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
19ec0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
19ed0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
19ee0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
19ef0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
19f00 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
19f10 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
19f20 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
19f30 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
19f40 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
19f50 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
19f60 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
19f70 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
19f80 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
19f90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
19fa0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
19fb0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
19fc0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
19fd0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19fe0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
19ff0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1a000 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1a010 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1a020 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1a030 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1a040 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1a050 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1a060 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a070 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1a080 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1a090 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1a0a0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1a0b0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1a0c0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1a0d0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1a0e0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1a0f0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1a100 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
1a110 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
1a120 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a  be one of:.**.**
1a130 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51   <dl>.** <dt>[SQ
1a140 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1a150 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1a160 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1a170 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1a180 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1a190 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1a1a0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1a1b0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1a1c0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1a1d0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
1a1e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1a1f0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1a200 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a210 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1a220 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1a230 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1a240 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1a250 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1a260 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1a270 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1a280 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1a290 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1a2a0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1a2b0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1a2c0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1a2d0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  returned.</dd>.*
1a2e0 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  *.** <dt>[SQLITE
1a2f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1a300 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
1a310 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
1a320 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1a330 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1a340 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1a350 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
1a360 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64  es it if.** it d
1a370 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
1a380 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
1a390 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
1a3a0 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
1a3b0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1a3c0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1a3d0 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
1a3e0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1a3f0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1a400 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1a410 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1a420 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1a430 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1a440 6e 20 61 62 6f 76 65 20 74 68 65 6e 20 74 68 65  n above then the
1a450 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1a460 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1a470 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1a480 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1a490 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1a4a0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1a4b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1a4c0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1a4d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
1a4e0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
1a4f0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
1a500 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
1a510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a520 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
1a530 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1a540 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
1a550 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
1a560 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
1a570 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
1a580 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
1a590 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
1a5a0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1a5b0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
1a5c0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
1a5d0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
1a5e0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
1a5f0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
1a600 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
1a610 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
1a620 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
1a630 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
1a640 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
1a650 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
1a660 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1a670 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1a680 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1a690 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1a6a0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1a6b0 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
1a6c0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1a6d0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1a6e0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1a6f0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1a700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a710 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1a720 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
1a730 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1a740 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1a750 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1a760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
1a770 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
1a780 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
1a790 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1a7a0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
1a7b0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1a7c0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
1a7d0 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
1a7e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1a7f0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1a800 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1a810 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a820 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1a830 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1a840 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1a850 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1a860 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1a870 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a880 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1a890 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a8a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1a8b0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1a8c0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1a8d0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1a8e0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1a8f0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1a900 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1a910 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1a920 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1a930 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1a940 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1a950 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1a960 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1a970 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
1a980 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1a990 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20  ** {F12701} The 
1a9a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1a9b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1a9c0 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
1a9d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1a9e0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1a9f0 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
1aa00 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1aa10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa20 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
1aa30 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
1aa40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1aa50 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
1aa60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1aa70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ..**.** {F12702}
1aa80 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
1aa90 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1aaa0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
1aab0 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
1aac0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
1aad0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
1aae0 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
1aaf0 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
1ab00 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
1ab10 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
1ab20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ab30 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33  ]..**.** {F12703
1ab40 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
1ab50 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1ab60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1ab70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ab80 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
1ab90 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1aba0 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70  v2()] writes a p
1abb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
1abc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1abd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1abe0 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a  ] into *ppDb..**
1abf0 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65  .** {F12704} The
1ac00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1ac10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1ac20 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  16()], and.**   
1ac30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1ac40 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
1ac50 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51  faces return [SQ
1ac60 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75  LITE_OK] upon su
1ac70 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ccess,.**       
1ac80 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72     or an appropr
1ac90 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
1aca0 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
1acb0 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65  .** {F12706} The
1acc0 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1acd0 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1ace0 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1acf0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1ad00 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1ad10 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
1ad20 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c  _open_v2()] will
1ad30 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   be UTF-8..**.**
1ad40 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65   {F12707} The de
1ad50 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1ad60 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1ad70 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1ad80 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1ad90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1ada0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1adb0 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  16..**.** {F1270
1adc0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1add0 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72  open(F,D)] inter
1ade0 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
1adf0 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1ae00 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1ae10 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65  v2(F,D,G,0)] whe
1ae20 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  re the G paramet
1ae30 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
1ae40 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
1ae50 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54  EADWRITE]|[SQLIT
1ae60 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a  E_OPEN_CREATE]..
1ae70 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49  **.** {F12711} I
1ae80 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1ae90 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1aea0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1aeb0 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1aec0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1aed0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1aee0 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74  READONLY] then t
1aef0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1af00 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
1af10 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e    for reading on
1af20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ly..**.** {F1271
1af30 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  2} If the G para
1af40 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1af50 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1af60 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1af70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1af80 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1af90 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74  PEN_READWRITE] t
1afa0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1afb0 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20   is opened.**   
1afc0 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61         reading a
1afd0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1afe0 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72  ssible, or for r
1aff0 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74  eading only if t
1b000 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1b010 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1b020 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1b030 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a  erating system..
1b040 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49  **.** {F12713} I
1b050 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1b060 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1b070 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en(v2(F,D,G,V)] 
1b080 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  omits the.**    
1b090 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1b0a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1b0b0 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1b0c0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1b0d0 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1b0e0 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20  ously exist, an 
1b0f0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1b100 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34  d..**.** {F12714
1b110 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1b120 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1b130 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56  _open(v2(F,D,G,V
1b140 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1b150 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1b160 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1b170 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
1b180 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1b190 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1b1a0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
1b1b0 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d  t, then an attem
1b1c0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72  pt is made to cr
1b1d0 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eate and.**     
1b1e0 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20       initialize 
1b1f0 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  the database..**
1b200 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20  .** {F12717} If 
1b210 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1b220 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1b230 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1b240 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
1b250 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
1b260 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b270 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  ] is ":memory:",
1b280 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65   then an private
1b290 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1b2a0 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f  hemeral, in-memo
1b2b0 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
1b2c0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1b2d0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20  onnection..**   
1b2e0 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1b2f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1b300 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1b310 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1b320 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1b330 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b340 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1b350 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68 65   {F12719} If the
1b360 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c   filename is NUL
1b370 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
1b380 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1b390 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
1b3a0 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64    ephemeral on-d
1b3b0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1b3c0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a  l be created..**
1b3d0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1b3e0 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1b3f0 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1b400 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1b410 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1b420 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1b430 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1b440 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65  .** {F12721} The
1b450 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b460 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62  ction] created b
1b470 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  y [sqlite3_open_
1b480 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20  v2(F,D,G,V)].** 
1b490 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73           will us
1b4a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  e the [sqlite3_v
1b4b0 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74  fs] object ident
1b4c0 69 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70  ified by the V p
1b4d0 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20  arameter,.**    
1b4e0 20 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66        or the def
1b4f0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1b500 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69  s] object if V i
1b510 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b520 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 33 7d  ..**.** {F12723}
1b530 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63   Two [database c
1b540 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
1b550 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
1b560 63 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65  cache if both we
1b570 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  re.**          o
1b580 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
1b590 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73  ame VFS while [s
1b5a0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1b5b0 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e  ] was enabled an
1b5c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  d.**          if
1b5d0 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20   both filenames 
1b5e0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73  compare equal us
1b5f0 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74  ing memcmp() aft
1b600 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a  er having been.*
1b610 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65  *          proce
1b620 73 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ssed by the [sql
1b630 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c  ite3_vfs | xFull
1b640 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64  Pathname] method
1b650 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a   of the VFS..*/.
1b660 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1b670 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1b680 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1b690 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1b6a0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1b6b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1b6c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1b6d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1b6e0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1b6f0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1b700 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1b710 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1b720 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1b730 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1b740 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1b750 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1b760 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1b770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b780 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1b790 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1b7a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1b7b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1b7c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1b7d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1b7e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1b7f0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1b800 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1b810 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1b820 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1b830 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1b840 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1b850 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1b860 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1b870 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
1b880 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12800}.**.** Th
1b890 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1b8a0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1b8b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1b8c0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1b8d0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1b8e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1b8f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1b900 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1b910 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1b920 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1b930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b940 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1b950 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1b960 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1b970 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1b980 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1b990 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1b9a0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1b9b0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1b9c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
1b9d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1b9e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
1b9f0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
1ba00 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
1ba10 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
1ba20 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1ba30 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
1ba40 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1ba50 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
1ba60 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ba70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
1ba80 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
1ba90 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
1baa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1bab0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1bac0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
1bad0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
1bae0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
1baf0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
1bb00 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
1bb10 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
1bb20 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
1bb30 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
1bb40 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1bb50 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
1bb60 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
1bb70 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
1bb80 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
1bb90 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
1bba0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
1bbb0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
1bbc0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
1bbd0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
1bbe0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
1bbf0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
1bc00 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
1bc10 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49   be set..**.** I
1bc20 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1bc30 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73   {F12801} The [s
1bc40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
1bc50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1bc60 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1bc70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65  .**          [re
1bc80 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
1bc90 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1bca0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1bcb0 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20  t recently.**   
1bcc0 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e         failed in
1bcd0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
1bce0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1bcf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1bd00 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1bd10 7b 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71  {F12803} The [sq
1bd20 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
1bd30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1bd40 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20  rmsg16(D)].**   
1bd50 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1bd60 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
1bd70 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
1bd80 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a  hat describes.**
1bd90 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72            the er
1bda0 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c  ror in the mostl
1bdb0 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  y recently faile
1bdc0 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1bdd0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  ,.**          en
1bde0 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20  coded as either 
1bdf0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1be00 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1be10 0a 2a 2a 20 7b 46 31 32 38 30 37 7d 20 54 68 65  .** {F12807} The
1be20 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1be30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
1be40 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
1be50 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1be60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
1be70 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1be80 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
1be90 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a  erface call..**.
1bea0 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c  ** {F12808} Call
1beb0 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
1bec0 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
1bed0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f  turn an error co
1bee0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  de.**          (
1bef0 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65  example: [sqlite
1bf00 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29  3_data_count()])
1bf10 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20   do not.**      
1bf20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65      change the e
1bf30 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73  rror code or mes
1bf40 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79  sage returned by
1bf50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1bf60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1bf70 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
1bf80 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  g()], or [sqlite
1bf90 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
1bfa0 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e  *.** {F12809} In
1bfb0 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72  terfaces that ar
1bfc0 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64  e not associated
1bfd0 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63   with a specific
1bfe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1bff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c000 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  n] (examples:.**
1c010 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c020 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72  e3_mprintf()] or
1c030 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1c040 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1c050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20  .**          do 
1c060 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1c070 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1c080 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1c090 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1c0a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1c0b0 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1c0c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1c0d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1c0e0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1c0f0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1c100 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1c110 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1c120 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1c130 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1c140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c150 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1c160 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30  t Object {F13000
1c170 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1c180 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c190 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1c1a0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1c1b0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1c1c0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1c1d0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1c1e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1c1f0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
1c200 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
1c210 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
1c220 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
1c230 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1c240 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1c250 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1c260 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
1c270 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1c280 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1c290 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1c2a0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1c2b0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1c2c0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1c2d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c2e0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1c2f0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1c300 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1c310 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
1c320 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
1c330 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1c340 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
1c350 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
1c360 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
1c370 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
1c380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1c390 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1c3a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
1c3b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
1c3c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1c3d0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
1c3e0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
1c3f0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
1c400 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
1c410 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
1c420 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
1c430 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1c440 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
1c450 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
1c460 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
1c470 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
1c480 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
1c490 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1c4a0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
1c4b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1c4c0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
1c4d0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
1c4e0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
1c4f0 65 20 4c 69 6d 69 74 73 20 7b 46 31 32 37 36 30  e Limits {F12760
1c500 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
1c510 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1c520 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1c530 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1c540 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1c550 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1c560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1c570 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1c580 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1c590 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c5a0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1c5b0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1c5c0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1c5d0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c5e0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1c5f0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1c600 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1c610 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1c620 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1c630 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1c640 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1c650 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1c660 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1c670 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68  t construct.  Th
1c680 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
1c690 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74  ns the old limit
1c6a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
1c6b0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
1c6c0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
1c6d0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
1c6e0 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68  anged..** For th
1c6f0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1c700 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1c710 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1c720 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f  hard upper.** bo
1c730 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d  und set by a com
1c740 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70  pile-time C prep
1c750 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e  rocessor macro n
1c760 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f  amed SQLITE_MAX_
1c770 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  XYZ..** (The "_L
1c780 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1c790 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1c7a0 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74   "_MAX_".).** At
1c7b0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
1c7c0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
1c7d0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
1c7e0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
1c7f0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
1c800 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
1c810 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52  r limit..**.** R
1c820 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un time limits a
1c830 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1c840 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1c850 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1c860 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1c870 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1c880 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1c890 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1c8a0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1c8b0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1c8c0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1c8d0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1c8e0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1c8f0 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68  ** webbrowser th
1c900 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1c910 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1c920 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1c930 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1c940 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1c950 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1c960 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1c970 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1c980 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1c990 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1c9a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1c9b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1c9c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1c9d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1c9e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1c9f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1ca00 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1ca10 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1ca20 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1ca30 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1ca40 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1ca50 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1ca60 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1ca70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1ca80 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1ca90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1caa0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1cab0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1cac0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1cad0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1cae0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1caf0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1cb00 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1cb10 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1cb20 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1cb30 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  A]..**.** This i
1cb40 6e 74 65 72 66 61 63 65 20 69 73 20 63 75 72 72  nterface is curr
1cb50 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
1cb60 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1cb70 64 20 69 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20  d is subject.** 
1cb80 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
1cb90 6f 76 61 6c 20 77 69 74 68 6f 75 74 20 70 72 69  oval without pri
1cba0 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a  or notice..**.**
1cbb0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1cbc0 2a 2a 20 7b 46 31 32 37 36 32 7d 20 41 20 73 75  ** {F12762} A su
1cbd0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1cbe0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1cbf0 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
1cc00 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  is.**          p
1cc10 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20  ositive changes 
1cc20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
1cc30 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
1cc40 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
1cc50 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1cc60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1cc70 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  to the lesser of
1cc80 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20   V and the hard 
1cc90 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  upper.**        
1cca0 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73    bound on the s
1ccb0 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73  ize of C that is
1ccc0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1ccd0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  time..**.** {F12
1cce0 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  766} A successfu
1ccf0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1cd00 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1cd10 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61   where V is nega
1cd20 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
1cd30 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74   leaves the stat
1cd40 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1cd50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1cd60 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
1cd70 2a 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63  * {F12769} A suc
1cd80 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1cd90 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1cda0 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74  ,C,V)] returns t
1cdb0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
1cdc0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
1cdd0 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1cde0 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1cdf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1ce00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ce10 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61  tion] D as it wa
1ce20 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  s prior to the c
1ce30 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  all..*/.int sqli
1ce40 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1ce50 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1ce60 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1ce70 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1ce80 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1ce90 69 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20  ies {F12790}.** 
1cea0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1ceb0 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69   category} {limi
1cec0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1ced0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1cee0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1cef0 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20  us aspects of a 
1cf00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1cf10 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61  tion].** that ca
1cf20 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20  n be limited in 
1cf30 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f  size by calls to
1cf40 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1cf50 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69  )]..** The meani
1cf60 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
1cf70 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73  us limits are as
1cf80 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1cf90 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
1cfa0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1cfb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1cfc0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1cfd0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
1cfe0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  OB or table row.
1cff0 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
1d000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1d010 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1d020 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1d030 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
1d040 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1d050 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1d060 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
1d070 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d080 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d090 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
1d0a0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
1d0b0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
1d0c0 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
1d0d0 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  T or the maximum
1d0e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1d0f0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
1d100 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
1d110 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
1d120 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
1d130 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1d140 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1d150 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d160 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1d170 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1d180 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1d190 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d1a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1d1b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1d1c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d1d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d1e0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1d1f0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1d200 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1d210 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1d220 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1d230 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d240 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1d250 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1d260 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1d270 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1d280 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1d290 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1d2a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1d2b0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1d2c0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
1d2d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d2e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1d2f0 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
1d300 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1d310 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1d320 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1d330 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d340 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64  mber of attached
1d350 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e   databases.</dd>
1d360 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1d370 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1d380 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
1d390 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d3a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
1d3b0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
1d3c0 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f  nt to the LIKE o
1d3d0 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74  r.** GLOB operat
1d3e0 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ors.</dd>.**.** 
1d3f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d400 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1d410 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d420 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1d430 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20  of variables in 
1d440 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1d450 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20   that can.** be 
1d460 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  bound.</dd>.** <
1d470 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1d480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1d490 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1d4a0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
1d4b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
1d4c0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
1d4d0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
1d4e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1d4f0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
1d500 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
1d510 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d520 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
1d530 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
1d540 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d550 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1d560 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
1d570 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d580 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
1d590 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
1d5a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d5b0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
1d5c0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
1d5d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d5e0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
1d5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
1d600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d610 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1d620 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
1d630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d640 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1d650 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
1d660 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  9../*.** CAPI3RE
1d670 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1d680 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
1d690 31 33 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  13010}.** KEYWOR
1d6a0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
1d6b0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
1d6c0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1d6d0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1d6e0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1d6f0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1d700 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1d710 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1d720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
1d730 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1d740 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
1d750 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
1d760 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
1d770 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
1d780 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
1d790 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1d7a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1d7b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1d7c0 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  n16()]..**.** Th
1d7d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1d7e0 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
1d7f0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
1d800 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
1d810 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
1d820 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1d830 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
1d840 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
1d850 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d860 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
1d870 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
1d880 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d890 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1d8a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
1d8b0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
1d8c0 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  ** If the nByte 
1d8d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1d8e0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1d8f0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1d900 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1d910 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1d920 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f  . If nByte is no
1d930 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1d940 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
1d950 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
1d960 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
1d970 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79   zSql.  When nBy
1d980 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1d990 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1d9a0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1d9b0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1d9c0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1d9d0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1d9e0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1d9f0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1da00 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1da10 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1da20 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1da30 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1da40 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1da50 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1da60 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1da70 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1da80 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1da90 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1daa0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1dab0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1dac0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1dad0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1dae0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1daf0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1db00 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1db10 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69  es..**.** *pzTai
1db20 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1db30 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
1db40 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
1db50 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  d of the.** firs
1db60 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1db70 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
1db80 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f  routines only co
1db90 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a  mpile the first.
1dba0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
1dbb0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
1dbc0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1dbd0 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e  g to what remain
1dbe0 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  s.** uncompiled.
1dbf0 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
1dc00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1dc10 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
1dc20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dc30 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
1dc40 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
1dc50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dc60 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ].  If there is 
1dc70 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1dc80 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1dc90 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
1dca0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1dcb0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
1dcc0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
1dcd0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
1dce0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
1dcf0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
1dd00 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31   NULL..** {A1301
1dd10 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  8} The calling p
1dd20 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1dd30 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1dd40 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1dd50 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1dd60 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1dd70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1dd80 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1dd90 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a  hed with it..**.
1dda0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
1ddb0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1ddc0 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73  turned, otherwis
1ddd0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1dde0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1ddf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1de00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
1de10 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1de20 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
1de30 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
1de40 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
1de50 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
1de60 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
1de70 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
1de80 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
1de90 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1dea0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
1deb0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
1dec0 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20  .** In the "v2" 
1ded0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1dee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1def0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
1df00 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
1df10 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1df20 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
1df30 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
1df40 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
1df50 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
1df60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1df70 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
1df80 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
1df90 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
1dfa0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1dfb0 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
1dfc0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1dfd0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
1dfe0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
1dff0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
1e000 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
1e010 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
1e020 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1e030 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1e040 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
1e050 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
1e060 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
1e070 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
1e080 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
1e090 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
1e0a0 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
1e0b0 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
1e0c0 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
1e0d0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
1e0e0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
1e0f0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
1e100 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
1e110 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
1e120 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
1e130 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
1e140 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1e150 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e160 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
1e170 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
1e180 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
1e190 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
1e1a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1e1b0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
1e1c0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
1e1d0 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
1e1e0 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
1e1f0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
1e200 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
1e210 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
1e220 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
1e230 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e240 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1e250 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1e260 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
1e270 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1e280 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54  error codes].  T
1e290 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1e2a0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1e2b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e2c0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1e2d0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1e2e0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1e2f0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f  t code.** and yo
1e300 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
1e310 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1e320 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
1e330 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
1e340 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
1e350 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1e360 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1e370 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1e380 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
1e390 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1e3a0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1e3b0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
1e3c0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1e3d0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
1e3e0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  /ol>.**.** INVAR
1e3f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1e400 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3011} The [sqlit
1e410 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53  e3_prepare(db,zS
1e420 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1e430 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e440 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1e450 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  zSql,...)] inter
1e460 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20  faces interpret 
1e470 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e480 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53  text in their zS
1e490 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  ql parameter as 
1e4a0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
1e4b0 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3012} The [sqlit
1e4c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c  e3_prepare16(db,
1e4d0 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a  zSql,...)] and.*
1e4e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e4f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e500 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
1e510 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
1e520 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
1e530 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
1e540 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
1e550 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1e560 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1e570 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  der..**.** {F130
1e580 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65  13} If the nByte
1e590 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1e5a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e5b0 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e  (db,zSql,nByte,.
1e5c0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1e5d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1e5e0 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  s is less than z
1e5f0 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78  ero, the SQL tex
1e600 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
1e610 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
1e620 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1e630 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1e640 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
1e650 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
1e660 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1e670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e680 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1e690 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1e6a0 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1e6b0 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
1e6c0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
1e6d0 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
1e6e0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1e6f0 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 64  SQL text is read
1e700 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a   from zSql..**.*
1e710 2a 20 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73  * {F13015} In [s
1e720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e730 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a  2(db,zSql,N,P,pz
1e740 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76  Tail)] and its v
1e750 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20  ariants.**      
1e760 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20      if the zSql 
1e770 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1e780 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ins more than on
1e790 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  e SQL statement.
1e7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
1e7b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1e7c0 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  LL, then *pzTail
1e7d0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1e7e0 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
1e7f0 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65 20       first byte 
1e800 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1e810 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1e820 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1e830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1e840 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a  do>What does *pz
1e850 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66  Tail point to if
1e860 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74   there is one st
1e870 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a  atement?</todo>.
1e880 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41  **.** {F13016} A
1e890 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1e8a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1e8b0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1e8c0 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a  N,ppStmt,...)].*
1e8d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e  *          or on
1e8e0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
1e8f0 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70  s writes into *p
1e900 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20  pStmt a pointer 
1e910 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  to a new.**     
1e920 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1e930 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70  tatement] or a p
1e940 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69  ointer to NULL i
1e950 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a  f zSql contains.
1e960 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68  **          noth
1e970 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77  ing other than w
1e980 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d  hitespace or com
1e990 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ments..**.** {F1
1e9a0 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3019} The [sqlit
1e9b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e9c0 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69   interface and i
1e9d0 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75  ts variants retu
1e9e0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  rn.**          [
1e9f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e  SQLITE_OK] or an
1ea00 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1ea10 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66  ror code] upon f
1ea20 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
1ea30 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73  13021} Before [s
1ea40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
1ea50 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53  b,zSql,nByte,ppS
1ea60 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20  tmt,pzTail)] or 
1ea70 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
1ea80 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73  variants returns
1ea90 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76   an error (any v
1eaa0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1eab0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a  [SQLITE_OK]),.**
1eac0 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20 66            they f
1ead0 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74  irst set *ppStmt
1eae0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
1eaf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1eb00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1eb10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1eb20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1eb30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1eb40 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1eb50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1eb60 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1eb70 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1eb80 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1eb90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1eba0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1ebb0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1ebc0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1ebd0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1ebe0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1ebf0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1ec00 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1ec10 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1ec20 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1ec30 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1ec40 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1ec50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1ec60 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1ec70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1ec80 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1ec90 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1eca0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1ecb0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1ecc0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ecd0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1ece0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ecf0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ed00 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1ed10 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ed20 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1ed30 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1ed40 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1ed50 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1ed60 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1ed70 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1ed80 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1ed90 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1eda0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1edb0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1edc0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1edd0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1ede0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1edf0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1ee00 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1ee10 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1ee20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1ee30 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1ee40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1ee50 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1ee60 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1ee70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1ee80 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1ee90 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1eea0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1eeb0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1eec0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1eed0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1eee0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1eef0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1ef00 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1ef10 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1ef20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1ef30 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1ef40 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1ef50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1ef60 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1ef70 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1ef80 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1ef90 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1efa0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1efb0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1efc0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1efd0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1efe0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1eff0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1f000 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1f010 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1f020 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46  Statement SQL {F
1f030 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  13100}.**.** Thi
1f040 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f050 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1f060 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1f070 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1f080 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1f090 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1f0a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f0b0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1f0c0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1f0d0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1f0e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f0f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1f100 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f110 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
1f120 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1f130 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
1f140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f150 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
1f160 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1f170 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f180 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1f190 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1f1a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1f1b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
1f1c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f1d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f1e0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
1f1f0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a  _sql()] returns.
1f200 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
1f210 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1f220 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1f230 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55  g containing a U
1f240 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a  TF-8 rendering.*
1f250 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1f260 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73  e original SQL s
1f270 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1f280 7b 46 31 33 31 30 32 7d 20 49 66 20 74 68 65 20  {F13102} If the 
1f290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f2a0 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
1f2b0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
1f2c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1f2d0 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
1f2e0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1f2f0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1f300 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
1f310 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f320 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
1f330 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
1f340 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ()] returns a NU
1f350 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1f360 2a 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73  * {F13103} The s
1f370 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
1f380 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53  y [sqlite3_sql(S
1f390 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  )] is valid unti
1f3a0 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  l the.**        
1f3b0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1f3c0 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65  ement] S is dele
1f3d0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1f3e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e  e3_finalize(S)].
1f3f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f400 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1f410 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1f420 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f430 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1f440 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1f450 74 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45  t {F15000}.** KE
1f460 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1f470 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1f480 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1f490 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1f4a0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1f4b0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1f4c0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1f4d0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1f4e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1f4f0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1f500 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1f510 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1f520 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1f530 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1f540 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
1f550 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1f560 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1f570 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1f580 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1f590 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1f5a0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1f5b0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1f5c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1f5d0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1f5e0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1f5f0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1f600 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1f610 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1f620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1f630 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1f640 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1f650 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1f660 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1f670 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f680 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1f690 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1f6a0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1f6b0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1f6c0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1f6d0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1f6e0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1f6f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1f700 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1f710 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1f720 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1f730 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1f740 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1f750 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1f760 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1f770 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1f780 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1f790 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1f7a0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1f7b0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1f7c0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1f7d0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1f7e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1f7f0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1f800 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1f810 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
1f820 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
1f830 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1f840 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1f850 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
1f860 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
1f870 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
1f880 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
1f890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1f8a0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
1f8b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
1f8c0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
1f8d0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1f8e0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1f8f0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1f900 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1f910 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1f920 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1f930 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
1f940 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
1f950 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
1f960 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
1f970 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
1f980 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
1f990 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
1f9a0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
1f9b0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62  nction between b
1f9c0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1f9d0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1f9e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1f9f0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
1fa00 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
1fa10 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1fa20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1fa30 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1fa40 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1fa50 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1fa60 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1fa70 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1fa80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1fa90 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1faa0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65  rotected..** The
1fab0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fac0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
1fad0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
1fae0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
1faf0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
1fb00 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
1fb10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fb20 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
1fb30 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
1fb40 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
1fb50 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1fb60 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
1fb70 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1fb80 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
1fb90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
1fba0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
1fbb0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1fbc0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
1fbd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1fbe0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
1fbf0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
1fc00 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
1fc10 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
1fc20 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
1fc30 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a  Object {F16001}.
1fc40 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1fc50 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1fc60 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1fc70 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1fc80 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1fc90 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1fca0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1fcb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1fcc0 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1fcd0 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1fce0 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1fcf0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1fd00 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1fd10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1fd20 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1fd30 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1fd40 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1fd50 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1fd60 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1fd70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1fd80 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1fd90 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1fda0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1fdb0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1fdc0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1fdd0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1fde0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1fdf0 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1fe00 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1fe10 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1fe20 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1fe30 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1fe40 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1fe50 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1fe60 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1fe70 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1fe80 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1fe90 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 46 31  d Statements {F1
1fea0 33 35 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  3500}.** KEYWORD
1feb0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
1fec0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
1fed0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
1fee0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
1fef0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
1ff00 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
1ff10 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
1ff20 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
1ff30 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
1ff40 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
1ff50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ff60 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
1ff70 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
1ff80 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
1ff90 61 63 65 64 20 62 79 20 61 20 70 61 72 61 6d 65  aced by a parame
1ffa0 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  ter in one of th
1ffb0 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  ese forms:.**.**
1ffc0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
1ffd0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
1ffe0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
1fff0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
20000 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
20010 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
20020 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
20030 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
20040 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
20050 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
20060 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d   is an alpha-num
20070 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e  eric parameter n
20080 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ame. The values 
20090 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
200a0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
200b0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
200c0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
200d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
200e0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
200f0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
20100 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
20110 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
20120 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
20130 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
20140 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
20150 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
20160 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
20170 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
20180 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
20190 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
201a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
201b0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
201c0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iants..**.** The
201d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
201e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
201f0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
20200 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
20210 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   The leftmost SQ
20220 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
20230 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
20240 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
20250 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
20260 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
20270 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
20280 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
20290 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
202a0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
202b0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
202c0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
202d0 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
202e0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
202f0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
20300 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
20310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20320 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
20330 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
20340 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
20350 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
20360 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
20370 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20   of NNN..** The 
20380 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
20390 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
203a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
203b0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
203c0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
203d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
203e0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
203f0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
20400 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
20410 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
20420 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
20430 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
20440 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
20450 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
20460 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
20470 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
20480 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20490 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
204a0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
204b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
204c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
204d0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
204e0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
204f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
20500 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
20510 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20520 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
20530 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
20540 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
20550 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20560 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
20570 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
20580 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
20590 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
205a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
205b0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
205c0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
205d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
205e0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
205f0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
20600 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
20610 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
20620 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
20630 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
20640 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
20650 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
20660 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
20670 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
20680 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
20690 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
206a0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
206b0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
206c0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
206d0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
206e0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
206f0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
20700 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
20710 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
20720 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
20730 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
20740 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
20750 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
20760 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
20770 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
20780 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
20790 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
207a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
207b0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
207c0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
207d0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
207e0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
207f0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
20800 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
20810 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
20820 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
20830 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
20840 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
20850 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
20860 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
20870 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
20880 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
20890 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
208a0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
208b0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
208c0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
208d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
208e0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
208f0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
20900 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
20910 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
20920 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
20930 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
20940 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
20950 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20960 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
20970 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
20980 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
20990 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
209a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
209b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
209c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
209d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
209e0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
209f0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
20a00 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
20a10 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
20a20 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
20a30 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
20a40 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
20a50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
20a60 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
20a70 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
20a80 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
20a90 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
20aa0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
20ab0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
20ac0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
20ad0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
20ae0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
20af0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
20b00 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
20b10 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
20b20 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
20b30 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
20b40 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
20b50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
20b60 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
20b70 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20b80 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
20b90 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
20ba0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
20bb0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
20bc0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
20bd0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
20be0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
20bf0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
20c00 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
20c10 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
20c20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
20c30 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
20c40 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
20c50 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
20c60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
20c70 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20c80 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
20c90 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
20ca0 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
20cb0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
20cc0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
20cd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20ce0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
20cf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20d00 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
20d10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
20d20 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20d30 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
20d40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
20d50 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20  13506} The [SQL 
20d60 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
20d70 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74  er] recognizes t
20d80 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
20d90 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22  ms.**          "
20da0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
20db0 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
20dc0 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61  "@VVV" as SQL pa
20dd0 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20  rameters,.**    
20de0 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20        where NNN 
20df0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
20e00 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64  of one or more d
20e10 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  igits.**        
20e20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20    and where VVV 
20e30 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
20e40 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  of one or more a
20e50 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  lphanumeric.**  
20e60 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65          characte
20e70 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
20e80 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
20e90 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  y a string conta
20ea0 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
20eb0 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20    no spaces and 
20ec0 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
20ed0 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
20ee0 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65  .** {F13509} The
20ef0 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
20f00 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
20f10 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
20f20 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69  * {F13512} The i
20f30 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
20f40 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
20f50 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
20f60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20f70 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
20f80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
20f90 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
20fa0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
20fb0 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
20fc0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
20fd0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
20fe0 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
20ff0 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
21000 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
21010 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
21020 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68  *.** {F13518} Th
21030 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
21040 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
21050 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
21060 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
21070 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
21080 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
21090 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
210a0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
210b0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
210c0 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
210d0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
210e0 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
210f0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
21100 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
21110 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
21120 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
21130 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
21140 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
21150 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
21160 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
21170 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
21180 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b  * {F13521} The [
21190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
211a0 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69  mpiler] fails wi
211b0 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41  th an [SQLITE_RA
211c0 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  NGE].**         
211d0 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
211e0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
211f0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
21200 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20  than 1.**       
21210 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68     or greater th
21220 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  an the compile-t
21230 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ime SQLITE_MAX_V
21240 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a  ARIABLE_NUMBER.*
21250 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
21260 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eter..**.** {F13
21270 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
21280 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21290 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
212a0 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
212b0 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
212c0 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
212d0 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
212e0 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
212f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
21300 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
21310 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21320 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  t] S..**.** {F13
21330 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
21340 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21350 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
21360 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
21370 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
21380 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
21390 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
213a0 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
213b0 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69  * {F13530} Bindi
213c0 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
213d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
213e0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
213f0 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
21400 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
21410 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
21420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21430 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  S)]..**.** {F135
21440 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
21450 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21460 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
21470 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21480 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
21490 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
214a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
214b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
214c0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
214d0 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
214e0 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
214f0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
21500 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  OB or string poi
21510 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
21520 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
21530 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21540 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d  ..**.** {F13536}
21550 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21560 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21570 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
21580 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21590 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
215a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
215b0 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
215c0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
215d0 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
215e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
215f0 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
21600 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
21610 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61  * {F13539} In ca
21620 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21630 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
21640 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
21650 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21660 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
21670 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
21680 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21690 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
216a0 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
216b0 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
216c0 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
216d0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
216e0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
216f0 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
21700 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
21710 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
21720 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
21730 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
21740 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
21750 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
21760 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
21770 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d  ..**.** {F13542}
21780 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21790 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
217a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
217b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
217c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
217d0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
217e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
217f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
21800 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
21810 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
21820 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
21830 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
21840 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
21850 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20  ine makes a.**  
21860 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
21870 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75  copy of the valu
21880 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65  e V before it re
21890 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  turns..**.** {F1
218a0 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3545} In calls t
218b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
218c0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
218d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
218e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
218f0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
21900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21910 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21920 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
21930 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65  en D is a pointe
21940 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
21950 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c   a function, SQL
21960 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74  ite invokes that
21970 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73   function to des
21980 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  troy the.**     
21990 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74       value V aft
219a0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
219b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c  ed using the val
219c0 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ue V..**.** {F13
219d0 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  548} In calls to
219e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
219f0 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29  eroblob(S,N,V,L)
21a00 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e  ] the value boun
21a10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
21a20 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74   a BLOB of L byt
21a30 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  es, or a zero-le
21a40 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69  ngth BLOB if L i
21a50 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
21a60 2a 20 7b 46 31 33 35 35 31 7d 20 49 6e 20 63 61  * {F13551} In ca
21a70 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21a80 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56  bind_value(S,N,V
21a90 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e  )] the V argumen
21aa0 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20  t may.**        
21ab0 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70    be either a [p
21ac0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
21ad0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f  _value] object o
21ae0 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
21af0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
21b00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
21b10 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
21b20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
21b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21b40 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
21b50 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
21b60 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
21b70 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
21b80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21b90 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
21ba0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
21bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21bc0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
21bd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
21be0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
21bf0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
21c00 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
21c10 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
21c20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
21c30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21c40 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
21c50 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21c60 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
21c70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
21c80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21c90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
21ca0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
21cb0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
21cc0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
21cd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
21ce0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
21cf0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
21d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
21d10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21d20 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
21d30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
21d40 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
21d50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
21d60 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
21d70 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13600}.**.** 
21d80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
21d90 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
21da0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
21db0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
21dc0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
21dd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
21de0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
21df0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
21e00 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
21e10 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
21e20 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
21e30 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
21e40 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
21e50 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
21e60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21e70 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
21e80 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
21e90 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
21ea0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
21eb0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
21ec0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
21ed0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
21ee0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
21ef0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
21f00 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
21f10 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
21f20 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
21f30 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
21f40 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
21f50 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
21f60 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
21f70 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
21f80 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
21f90 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
21fa0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21fb0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
21fc0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
21fd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21fe0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
21ff0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
22000 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22010 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22020 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22030 20 7b 46 31 33 36 30 31 7d 20 54 68 65 20 5b 73   {F13601} The [s
22040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22050 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20  meter_count(S)] 
22060 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22070 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
22080 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
22090 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  of all SQL param
220a0 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  eters in the.** 
220b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
220c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
220d0 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61   or 0 if S conta
220e0 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
220f0 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
22100 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22110 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
22120 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
22130 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
22140 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
22150 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a  eter {F13620}.**
22160 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22170 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22180 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
22190 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53  f the n-th.** [S
221a0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
221b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
221c0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20  tement]..** SQL 
221d0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
221e0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
221f0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
22200 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
22210 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
22220 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
22230 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
22240 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
22250 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
22260 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
22270 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
22280 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
22290 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
222a0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
222b0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
222c0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
222d0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
222e0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
222f0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
22300 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
22310 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64  re also referred
22320 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75   to as "anonymou
22330 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
22340 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
22350 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
22360 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
22370 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
22380 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
22390 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
223a0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
223b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
223c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
223d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
223e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
223f0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
22400 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
22410 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
22420 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
22430 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
22440 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
22450 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
22460 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
22470 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22480 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
22490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
224a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
224b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
224c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
224d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
224e0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
224f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22500 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
22510 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
22520 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54  **.** {F13621} T
22530 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
22540 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
22550 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22560 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
22570 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64      a UTF-8 rend
22580 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d  ering of the nam
22590 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  e of the SQL par
225a0 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20  ameter in.**    
225b0 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
225c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
225d0 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c   having index N,
225e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
225f0 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
22600 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
22610 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f  r with index N o
22620 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  r if the.**     
22630 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77       parameter w
22640 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61  ith index N is a
22650 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  n anonymous para
22660 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f  meter "?"..*/.co
22670 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22680 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22690 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
226a0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
226b0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
226c0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
226d0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
226e0 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a  me {F13640}.**.*
226f0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64  * Return the ind
22700 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
22710 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
22720 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69   name.  The.** i
22730 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
22740 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
22750 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
22760 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
22770 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
22780 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
22790 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72  _bind()].  A zer
227a0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
227b0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
227c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
227d0 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74  nd.  The paramet
227e0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
227f0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
22800 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
22810 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22820 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
22830 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
22840 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22850 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22860 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22870 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
22880 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22890 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
228a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
228b0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
228c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
228d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
228e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
228f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
22900 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  641} The [sqlite
22910 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22920 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74  _index(S,N)] int
22930 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
22940 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
22950 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
22960 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72  meter in the [pr
22970 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22980 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20  ].**          S 
22990 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68  whose name match
229a0 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  es the UTF-8 str
229b0 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74  ing N, or 0 if t
229c0 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20  here is.**      
229d0 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f      no match..*/
229e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
229f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
22a00 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
22a10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
22a20 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
22a30 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
22a40 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
22a50 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
22a60 20 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13660}.**.** 
22a70 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
22a80 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
22a90 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
22aa0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
22ab0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
22ac0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
22ad0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
22ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22af0 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73  nt]..** Use this
22b00 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
22b10 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
22b20 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
22b30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
22b40 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20  .**.** {F13661} 
22b50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  The [sqlite3_cle
22b60 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20  ar_bindings(S)] 
22b70 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
22b80 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20   all SQL.**     
22b90 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62       parameter b
22ba0 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b  indings in the [
22bb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22bc0 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55  nt] S back to NU
22bd0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
22be0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
22bf0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
22c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22c10 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
22c20 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
22c30 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a   Set {F13710}.**
22c40 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
22c50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22c60 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
22c70 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
22c80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
22c90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73  statement]. This
22ca0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22cb0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
22cc0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
22cd0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
22ce0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
22cf0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
22d00 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e  DATE])..**.** IN
22d10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
22d20 7b 46 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71  {F13711} The [sq
22d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
22d40 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
22d50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
22d60 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
22d70 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68     columns in th
22d80 65 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e  e result set gen
22d90 65 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70  erated by the [p
22da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22db0 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
22dc0 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73    or 0 if S does
22dd0 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20   not generate a 
22de0 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
22df0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
22e00 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
22e10 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
22e20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
22e30 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
22e40 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
22e50 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  720}.**.** These
22e60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
22e70 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
22e80 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
22e90 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
22ea0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
22eb0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
22ec0 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c  tement.  The sql
22ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22ee0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
22ef0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
22f00 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
22f10 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
22f20 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
22f30 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22f40 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
22f50 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
22f60 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
22f70 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
22f80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
22f90 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
22fa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
22fb0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
22fc0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
22fd0 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f  tement. The seco
22fe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
22ff0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
23000 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d  mber.  The leftm
23010 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
23020 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68  mber 0..**.** Th
23030 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
23040 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
23050 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
23060 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23070 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
23080 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
23090 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
230a0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
230b0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
230c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
230d0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
230e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
230f0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
23100 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69  n..**.** If sqli
23110 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
23120 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
23130 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
23140 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
23150 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
23160 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
23170 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
23180 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
23190 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
231a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
231b0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
231c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
231d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
231e0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
231f0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
23200 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
23210 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
23220 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
23230 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
23240 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
23250 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
23260 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
23270 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
23280 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
23290 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
232a0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
232b0 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75  ** {F13721} A su
232c0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
232d0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
232e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
232f0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
23300 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
23310 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  rns the name of 
23320 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
23330 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20  where 0 is.**   
23340 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d         the leftm
23350 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
23360 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
23370 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
23380 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
23390 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65  ement] S as a ze
233a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
233b0 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
233c0 2a 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63  * {F13723} A suc
233d0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
233e0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
233f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23400 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
23410 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
23420 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
23430 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23440 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
23450 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
23460 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
23470 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
23480 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
23490 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
234a0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
234b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
234c0 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
234d0 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
234e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
234f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34  r..**.** {F13724
23500 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23510 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
23520 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
23530 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20  n_name16()].**  
23540 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
23550 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
23560 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79   pointer if they
23570 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a   are unable to.*
23580 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
23590 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
235a0 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20  ld their normal 
235b0 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a  return strings..
235c0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49  **.** {F13725} I
235d0 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
235e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  r to [sqlite3_co
235f0 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  lumn_name(S,N)] 
23600 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
23610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
23620 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f  ame16(S,N)] is o
23630 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
23640 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
23650 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
23660 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
23670 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  er..**.** {F1372
23680 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  6} The strings r
23690 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
236a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
236b0 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  S,N)] and.**    
236c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
236d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
236e0 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  )] are valid unt
236f0 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20  il the next.**  
23700 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20          call to 
23710 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77  either routine w
23720 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61  ith the same S a
23730 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a  nd N parameters.
23740 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
23750 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  ntil [sqlite3_fi
23760 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61  nalize(S)] is ca
23770 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lled..**.** {F13
23780 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75  727} When a resu
23790 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b  lt column of a [
237a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
237b0 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  t contains.**   
237c0 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61         an AS cla
237d0 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  use, the name of
237e0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
237f0 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a  the identifier.*
23800 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
23810 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41  e right of the A
23820 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f  S keyword..*/.co
23830 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23840 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
23850 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23860 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
23870 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23880 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
23890 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
238a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
238b0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
238c0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
238d0 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13740}.**.** T
238e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
238f0 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
23900 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
23910 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
23920 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
23930 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
23940 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  lt of a [SELECT]
23950 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
23960 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
23970 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
23980 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
23990 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
239a0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
239b0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
239c0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
239d0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
239e0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
239f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
23a00 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
23a10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
23a20 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
23a30 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
23a40 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
23a50 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
23a60 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
23a70 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
23a80 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
23a90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23aa0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
23ab0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
23ac0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
23ad0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
23ae0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
23af0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
23b00 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
23b10 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
23b20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
23b30 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
23b40 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
23b50 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
23b60 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
23b70 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
23b80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
23b90 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
23ba0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
23bb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23bc0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
23bd0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
23be0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
23bf0 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
23c00 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
23c10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
23c20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
23c30 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
23c40 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
23c50 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23c60 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
23c70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
23c80 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
23c90 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
23ca0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
23cb0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
23cc0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
23cd0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
23ce0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
23cf0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
23d00 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
23d10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
23d20 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
23d30 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
23d40 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
23d50 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
23d60 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
23d70 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
23d80 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
23d90 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
23da0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
23db0 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
23dc0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
23dd0 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
23de0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
23df0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
23e00 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
23e10 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
23e20 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
23e30 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
23e40 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
23e50 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
23e60 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
23e70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
23e80 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
23e90 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
23ea0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
23eb0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
23ec0 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a  **.** {A13751}.*
23ed0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
23ee0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
23ef0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
23f00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
23f10 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
23f20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23f30 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
23f40 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
23f50 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
23f60 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
23f70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
23f80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34  TS:.**.** {F1374
23f90 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
23fa0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
23fb0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
23fc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
23fd0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
23fe0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
23ff0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
24000 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
24010 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
24020 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
24030 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
24040 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24050 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
24060 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
24070 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
24080 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
24090 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
240a0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
240b0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
240c0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
240d0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
240e0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
240f0 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71  {F13742} The [sq
24100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
24110 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e  abase_name16(S,N
24120 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24130 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
24140 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
24150 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
24160 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
24170 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
24180 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
24190 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68        from which
241a0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
241b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
241c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
241d0 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20  t] S is.**      
241e0 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f      extracted, o
241f0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
24200 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
24210 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
24220 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ssion.**        
24230 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74    or if unable t
24240 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24250 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e  y to store the n
24260 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ame..**.** {F137
24270 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  43} The [sqlite3
24280 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
24290 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
242a0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
242b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
242c0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
242d0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
242e0 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77  the table from w
242f0 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20  hich the.**     
24300 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
24310 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70  column of the [p
24320 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24330 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
24340 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  d,.**          o
24350 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
24360 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
24370 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
24380 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ssion.**        
24390 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74    or if unable t
243a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
243b0 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e  y to store the n
243c0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ame..**.** {F137
243d0 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  44} The [sqlite3
243e0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
243f0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
24400 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
24410 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
24420 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
24430 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
24440 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
24450 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
24460 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
24470 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
24480 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
24490 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
244a0 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
244b0 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
244c0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
244d0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
244e0 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
244f0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
24500 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
24510 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
24520 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
24530 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
24540 7b 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71  {F13745} The [sq
24550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
24560 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  gin_name(S,N)] i
24570 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24580 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24590 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
245a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
245b0 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
245c0 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
245d0 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
245e0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
245f0 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
24600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24610 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
24620 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
24630 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
24640 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
24650 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
24660 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
24670 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
24680 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24690 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
246a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 36 7d  ..**.** {F13746}
246b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
246c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
246d0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
246e0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
246f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24700 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
24710 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
24720 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
24730 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
24740 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20           column 
24750 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
24760 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
24770 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
24780 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24790 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
247a0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
247b0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
247c0 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  mn.**          o
247d0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
247e0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
247f0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
24800 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
24810 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
24820 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24830 20 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72 65   {F13748} The re
24840 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d  turn values from
24850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24860 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
24870 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
24880 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
24890 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20  erfaces].**     
248a0 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 66       are valid f
248b0 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  or the lifetime 
248c0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
248d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
248e0 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
248f0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
24900 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74   changed by anot
24910 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  her metadata.** 
24920 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
24930 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20  ce call for the 
24940 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74  same prepared st
24950 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
24960 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  mn..**.** LIMITA
24970 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
24980 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20  3751} If two or 
24990 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
249a0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
249b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
249c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
249d0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
249e0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
249f0 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
24a00 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b    for the same [
24a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24a20 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
24a30 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20  olumn.**        
24a40 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69    at the same ti
24a50 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
24a60 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
24a70 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
24a80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24a90 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
24aa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
24ab0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24ac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
24ad0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
24ae0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
24af0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
24b00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
24b10 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
24b20 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
24b30 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24b40 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
24b50 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
24b60 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
24b70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
24b80 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
24b90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
24ba0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24bb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
24bc0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
24bd0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
24be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24bf0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
24c00 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
24c10 73 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a  sult {F13760}.**
24c20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
24c30 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
24c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24c50 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
24c60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
24c70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
24c80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
24c90 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
24ca0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
24cb0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
24cc0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
24cd0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
24ce0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
24cf0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
24d00 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
24d10 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
24d20 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
24d30 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
24d40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
24d50 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
24d60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
24d70 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
24d80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
24d90 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
24da0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24db0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
24dc0 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a  encoded. {END}.*
24dd0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
24de0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
24df0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
24e00 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
24e10 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
24e20 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
24e30 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
24e40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
24e50 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
24e60 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
24e70 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
24e80 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
24e90 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
24ea0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
24eb0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
24ec0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
24ed0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
24ee0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
24ef0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
24f00 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
24f10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
24f20 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
24f30 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
24f40 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
24f50 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
24f60 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
24f70 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
24f80 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
24f90 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
24fa0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
24fb0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
24fc0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
24fd0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
24fe0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
24ff0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
25000 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
25010 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
25020 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
25030 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
25040 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
25050 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
25060 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
25070 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25080 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20  .**.** {F13761} 
25090 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
250a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
250b0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
250c0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a  ,N)] returns a.*
250d0 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  *           zero
250e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
250f0 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
25100 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64  ing the declared
25110 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20   datatype.**    
25120 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61         of the ta
25130 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
25140 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e  appears as the N
25150 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
25160 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
25170 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
25180 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
25190 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
251a0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
251b0 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {F13762}  A succ
251c0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
251d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
251e0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
251f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
25200 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
25210 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
25220 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
25230 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
25240 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
25250 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
25260 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
25270 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
25280 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
25290 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
252a0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
252b0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
252c0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
252d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
252e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
252f0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
25300 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
25310 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
25320 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
25330 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
25340 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
25350 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25360 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25370 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
25380 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74           or if t
25390 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
253a0 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73   S is an express
253b0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20  ion or subquery 
253c0 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  rather.**       
253d0 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65      than a table
253e0 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61   column, or if a
253f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
25400 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20  on failure.**   
25410 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
25420 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63  uring encoding c
25430 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e  onversions, then
25440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
25450 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
25460 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
25470 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
25480 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
25490 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
254a0 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55  (S,N)] return NU
254b0 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  LL..*/.const cha
254c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
254d0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
254e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
254f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
25500 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
25510 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
25520 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
25530 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
25540 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
25550 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a  ent {F13200}.**.
25560 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
25570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25580 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
25590 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
255a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
255b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
255c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
255d0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
255e0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
255f0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
25600 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
25610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25620 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
25630 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
25640 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
25650 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
25660 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
25670 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
25680 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
25690 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
256a0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
256b0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
256c0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
256d0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
256e0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
256f0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
25700 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
25710 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
25720 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
25730 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
25740 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
25750 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
25760 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
25770 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
25780 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
25790 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
257a0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
257b0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
257c0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
257d0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
257e0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
257f0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
25800 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
25810 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67  **.** In the leg
25820 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
25830 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25840 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
25850 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
25860 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
25870 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
25880 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
25890 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
258a0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
258b0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
258c0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
258d0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
258e0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
258f0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
25900 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
25910 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
25920 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
25930 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
25940 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
25950 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
25960 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
25970 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
25980 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
25990 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
259a0 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
259b0 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
259c0 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
259d0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
259e0 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
259f0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
25a00 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
25a10 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
25a20 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
25a30 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
25a40 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
25a50 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
25a60 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
25a70 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
25a80 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
25a90 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  g..**.** [SQLITE
25aa0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
25ab0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
25ac0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
25ad0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
25ae0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
25af0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
25b00 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
25b10 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
25b20 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
25b30 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
25b40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
25b50 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
25b60 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
25b70 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
25b80 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
25b90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
25ba0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
25bb0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
25bc0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
25bd0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
25be0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
25bf0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
25c00 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
25c10 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
25c20 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
25c30 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
25c40 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
25c50 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
25c60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
25c70 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
25c80 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
25c90 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
25ca0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
25cb0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53  f data..**.** [S
25cc0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
25cd0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
25ce0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
25cf0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
25d00 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
25d10 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
25d20 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
25d30 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
25d40 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
25d50 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
25d60 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
25d70 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
25d80 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
25d90 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67  .** With the leg
25da0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
25db0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
25dc0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
25dd0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
25de0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
25df0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
25e00 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
25e10 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
25e20 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
25e30 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
25e40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25e50 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
25e60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
25e70 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
25e80 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
25e90 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
25ea0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
25eb0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
25ec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
25ed0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
25ee0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
25ef0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
25f00 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
25f10 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
25f20 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
25f30 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
25f40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25f50 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
25f60 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
25f70 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
25f80 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
25f90 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
25fa0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
25fb0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
25fc0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
25fd0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
25fe0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
25ff0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
26000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26010 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
26020 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
26030 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
26040 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
26050 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  time..**.** <b>G
26060 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
26070 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
26080 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
26090 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
260a0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
260b0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
260c0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
260d0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
260e0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
260f0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
26100 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
26110 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
26120 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
26130 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
26140 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
26150 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26160 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
26170 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
26180 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
26190 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
261a0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
261b0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
261c0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
261d0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
261e0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
261f0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
26200 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
26210 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
26220 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
26230 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
26240 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
26250 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
26260 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
26270 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26280 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
26290 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
262a0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
262b0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
262c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
262d0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
262e0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
262f0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
26300 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
26310 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
26320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
26330 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
26340 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
26350 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
26360 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
26370 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20  .**.** {F13202} 
26380 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
26390 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
263a0 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 75  s ready to be ru
263b0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
263c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
263d0 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20  ep(S)] advances 
263e0 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74  that prepared st
263f0 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a  atement until.**
26400 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c             compl
26410 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69  etion or until i
26420 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65  t is ready to re
26430 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77  turn another row
26440 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
26450 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c       result set,
26460 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71   or until an [sq
26470 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
26480 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20  | interrupt].** 
26490 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72            or a r
264a0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63  un-time error oc
264b0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  curs..**.** {F15
264c0 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  304}  When a cal
264d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
264e0 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68  ep(S)] causes th
264f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26500 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
26510 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20      S to run to 
26520 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20  completion, the 
26530 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
26540 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
26550 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20  **.** {F15306}  
26560 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
26570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26580 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69   stops because i
26590 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a  t is ready to.**
265a0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
265b0 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  n another row of
265c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c   the result set,
265d0 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
265e0 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ROW]..**.** 
265f0 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61 20 63  {F15308}  If a c
26600 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26610 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74  step(S)] encount
26620 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ers an.**       
26630 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74      [sqlite3_int
26640 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
26650 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d  pt] or a run-tim
26660 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20  e error,.**     
26670 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73        it returns
26680 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
26690 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20  error code that 
266a0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a  is not one of.**
266b0 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
266c0 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f  TE_OK], [SQLITE_
266d0 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROW], or [SQLITE
266e0 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
266f0 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73  15310}  If an [s
26700 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
26710 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72   | interrupt] or
26720 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
26730 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  r.**           o
26740 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63  ccurs during a c
26750 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26760 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20  step(S)].**     
26770 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65        for a [pre
26780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26790 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67   S created using
267a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65  .**           le
267b0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20  gacy interfaces 
267c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
267d0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
267e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
267f0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
26800 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
26810 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
26820 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
26830 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45  _ERROR], [SQLITE
26840 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BUSY], or [SQLI
26850 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69  TE_MISUSE]..*/.i
26860 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
26870 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
26880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26890 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
268a0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
268b0 65 74 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a  et {F13770}.**.*
268c0 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
268d0 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
268e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
268f0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
26900 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
26910 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
26920 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63  3771}  After a c
26930 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26940 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65  step(S)] that re
26950 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
26960 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  W],.**          
26970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
26980 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
26990 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
269a0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a   the same value.
269b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
269c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
269d0 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
269e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nction..**.** {F
269f0 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
26a00 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
26a10 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
26a20 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
26a30 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
26a40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
26a50 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
26a60 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
26a70 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a   called on the.*
26a80 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
26a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26aa0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
26ab0 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
26ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
26ad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
26ae0 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73   prepared] or [s
26af0 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72  qlite3_reset | r
26b00 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  eset],.**       
26b10 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
26b20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
26b30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
26b40 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
26b50 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
26b60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
26b70 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26b80 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
26b90 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46 31  al Datatypes {F1
26ba0 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0265}.** KEYWORD
26bb0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
26bc0 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 20 45 76  *.** {F10266} Ev
26bd0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
26be0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
26bf0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
26c00 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
26c10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
26c20 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
26c30 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
26c40 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
26c50 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
26c60 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
26c70 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
26c80 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20  > NULL.** </ul> 
26c90 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
26ca0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
26cb0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
26cc0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
26cd0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
26ce0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
26cf0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
26d00 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
26d10 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
26d20 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
26d30 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
26d40 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
26d50 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
26d60 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
26d70 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
26d80 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
26d90 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
26da0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
26db0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
26dc0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
26dd0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
26de0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
26df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
26e00 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
26e10 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
26e20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
26e30 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
26e40 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
26e50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
26e60 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
26e70 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
26e80 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
26e90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26ea0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
26eb0 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30  m A Query {F1380
26ec0 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
26ed0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
26ee0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
26ef0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
26f00 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
26f10 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72  set query" inter
26f20 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  face..**.** Thes
26f30 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26f40 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
26f50 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
26f60 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
26f70 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
26f80 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e   of a query.  In
26f90 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
26fa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
26fb0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
26fc0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
26fd0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
26fe0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
26ff0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
27000 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
27010 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
27020 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
27030 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
27040 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
27050 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
27060 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
27070 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
27080 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
27090 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
270a0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
270b0 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  ed.  The leftmos
270c0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
270d0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
270e0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a  he index 0..**.*
270f0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
27100 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
27110 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
27120 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
27130 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
27140 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
27150 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
27160 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
27170 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
27180 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
27190 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
271a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
271b0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
271c0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
271d0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
271e0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
271f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
27200 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
27210 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
27220 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
27230 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
27240 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
27250 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
27260 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
27270 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
27280 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
27290 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
272a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
272b0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
272c0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
272d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
272e0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
272f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
27300 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
27310 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
27320 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
27330 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27340 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
27350 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
27360 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
27370 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
27380 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
27390 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
273a0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
273b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
273c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
273d0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
273e0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
273f0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
27400 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
27410 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
27420 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
27430 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
27440 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61   The returned va
27450 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
27460 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
27470 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
27480 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
27490 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
274a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
274b0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
274c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
274d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
274e0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
274f0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
27500 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
27510 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
27520 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
27530 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
27540 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
27550 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
27560 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
27570 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
27580 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
27590 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
275a0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
275b0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
275c0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
275d0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
275e0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
275f0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
27600 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
27610 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
27620 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
27630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27640 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
27650 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
27660 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
27670 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
27680 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
27690 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
276a0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
276b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
276c0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
276d0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
276e0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
276f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
27700 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
27710 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
27720 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
27730 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
27740 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
27750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
27760 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
27770 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
27780 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
27790 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
277a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
277b0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
277c0 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
277d0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
277e0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
277f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
27800 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
27810 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
27820 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
27830 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
27840 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
27850 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
27860 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
27870 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
27880 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
27890 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
278a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
278b0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
278c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
278d0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
278e0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
278f0 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
27900 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a  ed.  The return.
27910 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
27920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
27930 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
27940 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e  ength BLOB is an
27950 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
27960 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
27970 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
27980 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
27990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
279a0 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
279b0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
279c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
279d0 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
279e0 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
279f0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
27a00 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
27a10 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
27a20 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * The zero termi
27a30 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
27a40 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
27a50 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  unt..**.** The o
27a60 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
27a70 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
27a80 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
27a90 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
27aa0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
27ab0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
27ac0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27ad0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
27ae0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
27af0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
27b00 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
27b10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
27b20 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
27b30 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
27b40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27b50 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
27b60 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
27b70 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
27b80 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
27b90 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
27ba0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
27bb0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
27bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
27bd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
27be0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
27bf0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
27c00 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
27c10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
27c20 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27c30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
27c40 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
27c50 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
27c60 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
27c70 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
27c80 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
27c90 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
27ca0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
27cb0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
27cc0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
27cd0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
27ce0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
27cf0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
27d00 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
27d10 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
27d20 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
27d30 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
27d40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
27d50 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
27d60 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
27d70 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
27d80 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
27d90 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
27da0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
27db0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
27dc0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
27dd0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
27de0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
27df0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
27e00 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
27e10 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
27e20 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
27e30 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
27e40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
27e50 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
27e60 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
27e70 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
27e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
27e90 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
27ea0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
27eb0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
27ec0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
27ed0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
27ee0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
27ef0 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
27f00 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
27f10 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
27f20 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
27f30 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
27f40 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
27f50 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
27f60 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
27f70 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
27f80 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
27f90 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
27fa0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
27fb0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
27fc0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
27fd0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
27fe0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
27ff0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
28000 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
28010 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
28020 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
28030 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28040 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
28050 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
28060 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
28070 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
28080 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
28090 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
280a0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
280b0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
280c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
280d0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
280e0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
280f0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
28100 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
28110 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
28120 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
28130 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
28140 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
28150 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
28160 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
28170 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
28180 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
28190 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
281a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
281b0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
281c0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
281d0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
281e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
281f0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
28200 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
28210 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
28220 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
28230 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
28240 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
28250 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
28260 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
28270 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
28280 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
28290 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
282a0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
282b0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
282c0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
282d0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
282e0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
282f0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
28300 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
28310 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
28320 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
28330 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
28340 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
28350 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
28360 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
28370 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
28380 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
28390 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
283a0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
283b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
283c0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
283d0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
283e0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
283f0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
28400 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
28410 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
28420 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
28430 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
28440 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
28450 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
28460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28470 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
28480 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
28490 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
284a0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
284b0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
284c0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
284d0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
284e0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
284f0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
28500 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
28510 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
28520 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
28530 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
28540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28550 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
28560 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
28570 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
28580 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
28590 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
285a0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
285b0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
285c0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
285d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
285e0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
285f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
28600 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
28610 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
28620 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
28630 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
28640 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f  * </ul>.**.** Co
28650 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
28660 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
28670 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
28680 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
28690 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
286a0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
286b0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
286c0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
286d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
286e0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
286f0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
28700 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
28710 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
28720 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
28730 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
28740 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
28750 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
28760 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
28770 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
28780 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
28790 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
287a0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
287b0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
287c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
287d0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
287e0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
287f0 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
28800 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
28810 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
28820 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
28830 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
28840 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
28850 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
28860 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28870 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
28880 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
28890 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
288a0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
288b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
288c0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
288d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
288e0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
288f0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
28900 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
28910 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
28920 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
28930 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
28940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28950 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
28960 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
28970 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
28980 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
28990 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
289a0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
289b0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
289c0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
289d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
289e0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
289f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
28a00 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
28a10 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
28a20 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
28a30 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
28a40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
28a50 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
28a60 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
28a70 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
28a80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28a90 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
28aa0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
28ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28ac0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
28ad0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
28ae0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
28af0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73  .** The pointers
28b00 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
28b10 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
28b20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
28b30 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
28b40 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
28b50 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
28b60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
28b70 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
28b80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28b90 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
28ba0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
28bb0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
28bc0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
28bd0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
28be0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
28bf0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
28c00 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
28c10 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
28c20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
28c30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28c40 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
28c50 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
28c60 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  free()]..**.** I
28c70 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28c80 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
28c90 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
28ca0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
28cb0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
28cc0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
28cd0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
28ce0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
28cf0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
28d00 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
28d10 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
28d20 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
28d30 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
28d40 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
28d50 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
28d60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
28d70 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
28d80 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
28d90 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
28da0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20  .**.** {F13803} 
28db0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28dc0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69  umn_blob(S,N)] i
28dd0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
28de0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28df0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
28e00 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
28e10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28e20 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
28e30 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
28e40 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
28e50 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65  o a BLOB and the
28e60 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  n returns a.**  
28e70 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
28e80 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
28e90 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
28ea0 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13806} The [sqli
28eb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28ec0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28ed0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
28ee0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
28ef0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28f00 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
28f10 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
28f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
28f30 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
28f40 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
28f50 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
28f60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28f70 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
28f80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
28f90 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
28fa0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
28fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28fc0 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  ext(S,N)]..**.**
28fd0 20 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73   {F13809} The [s
28fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28ff0 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  tes16(S,N)] inte
29000 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
29010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
29020 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
29030 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
29040 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
29050 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
29060 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
29070 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
29080 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
29090 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
290a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
290b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
290c0 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a  n_text16(S,N)]..
290d0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54  **.** {F13812} T
290e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
290f0 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20  mn_double(S,N)] 
29100 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
29110 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
29120 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
29130 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
29140 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
29150 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
29160 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
29170 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
29180 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
29190 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
291a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
291b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
291c0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
291d0 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  13815} The [sqli
291e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53  te3_column_int(S
291f0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
29200 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29210 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29220 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29230 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29240 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
29250 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
29260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29270 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
29280 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
29290 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
292a0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
292b0 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
292c0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
292d0 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {F13818} The [s
292e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
292f0 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
29300 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
29310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
29320 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
29330 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
29340 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
29350 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29360 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29370 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
29380 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
29390 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
293a0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
293b0 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65  opy of that inte
293c0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ger..**.** {F138
293d0 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
293e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
293f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
29400 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
29410 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
29420 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29430 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29440 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
29450 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
29460 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29470 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
29480 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
29490 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
294a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
294b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
294c0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
294d0 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3824} The [sqlit
294e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
294f0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
29500 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
29510 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
29520 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29530 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29540 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
29550 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
29560 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29570 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
29580 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
29590 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
295a0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
295b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
295c0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
295d0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
295e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
295f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
29600 46 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c  F13827} The [sql
29610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
29620 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
29630 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
29640 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
29650 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
29660 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
29670 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
29680 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
29690 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
296a0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
296b0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
296c0 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20          the Nth 
296d0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
296e0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
296f0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
29700 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
29710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29720 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
29730 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  13830} The [sqli
29740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29750 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
29760 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
29770 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
29780 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  o an [unprotecte
29790 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
297a0 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a   object for the.
297b0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
297c0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
297d0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
297e0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
297f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
29800 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29810 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74  ent] S..*/.const
29820 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29830 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
29840 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
29850 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
29860 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
29870 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29880 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
29890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
298a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
298b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
298c0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
298d0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
298e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
298f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
29900 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
29910 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
29920 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
29930 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
29940 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
29950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29960 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
29970 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
29980 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
29990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
299a0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
299b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
299c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
299d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
299e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
299f0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
29a00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29a10 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
29a20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29a30 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
29a40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29a50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29a60 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
29a70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
29a80 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a  bject {F13300}.*
29a90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29aa0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
29ab0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
29ac0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
29ad0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29ae0 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65  .** If the state
29af0 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
29b00 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
29b10 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
29b20 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
29b30 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
29b40 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69  rned. If executi
29b50 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
29b60 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
29b70 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
29b80 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
29b90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
29ba0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
29bb0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
29bc0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
29bd0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
29be0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
29bf0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29c00 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
29c10 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
29c20 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
29c30 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
29c40 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
29c50 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
29c60 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
29c70 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
29c80 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
29c90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
29ca0 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
29cb0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
29cc0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
29cd0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
29ce0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
29cf0 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
29d00 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
29d10 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
29d20 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
29d30 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
29d40 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
29d50 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29d60 2a 0a 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68  *.** {F11302} Th
29d70 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
29d80 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
29d90 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
29da0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
29db0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29dc0 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
29dd0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
29de0 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
29df0 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
29e00 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
29e10 0a 2a 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20  .** {F11304} If 
29e20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29e30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29e40 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
29e50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
29e60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29e70 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
29e80 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
29e90 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
29ea0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
29eb0 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
29ec0 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
29ed0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29ee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29ef0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29f00 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
29f10 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29f20 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30  t Object {F13330
29f30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
29f40 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
29f50 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
29f60 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
29f70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
29f80 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
29f90 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
29fa0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
29fb0 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
29fc0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
29fd0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
29fe0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
29ff0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2a000 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2a010 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2a020 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2a030 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2a040 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2a050 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a060 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2a070 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2a080 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54  **.** {F11332} T
2a090 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2a0a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2a0b0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2a0c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a0d0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
2a0e0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2a0f0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2a100 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  am..**.** {F1133
2a110 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2a120 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a130 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a140 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a150 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a160 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2a170 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2a180 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2a190 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
2a1a0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2a1b0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2a1c0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2a1d0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
2a1e0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2a1f0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2a200 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2a210 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36  ]..**.** {F11336
2a220 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2a230 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a240 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2a250 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a260 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a270 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2a280 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2a290 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
2a2a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a2b0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2a2c0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2a2d0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  code]..**.** {F1
2a2e0 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  1338} The [sqlit
2a2f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2a300 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2a310 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2a320 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
2a330 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2a340 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2a350 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2a360 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2a370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a380 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2a390 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2a3a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2a3b0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2a3c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  SQL Functions {F
2a3d0 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  16100}.** KEYWOR
2a3e0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2a3f0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2a400 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2a410 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a420 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2a430 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2a440 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a450 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2a460 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77  }.**.** These tw
2a470 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
2a480 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2a490 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2a4a0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2a4b0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2a4c0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2a4d0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2a4e0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2a4f0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2a500 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2a510 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2a520 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2a530 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
2a540 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
2a550 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
2a560 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
2a570 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
2a580 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
2a590 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
2a5a0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
2a5b0 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
2a5c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a5d0 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
2a5e0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2a5f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2a600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2a610 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2a620 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2a630 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2a640 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2a650 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2a660 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
2a670 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  le program uses 
2a680 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2a690 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2a6a0 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  tion internally,
2a6b0 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69   then SQL functi
2a6c0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2a6d0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
2a6e0 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61  o.** each databa
2a6f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2a700 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2a710 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2a720 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2a730 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2a740 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2a750 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65  defined.  The le
2a760 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2a770 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2a780 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
2a790 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65  ive of.** the ze
2a7a0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
2a7b0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2a7c0 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
2a7d0 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
2a7e0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
2a7f0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
2a800 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2a810 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2a820 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2a830 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45  ult in [SQLITE_E
2a840 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75  RROR] being retu
2a850 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2a860 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2a870 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2a880 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2a890 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a8a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2a8b0 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
2a8c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
2a8d0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2a8e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2a8f0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
2a900 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
2a910 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
2a920 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
2a930 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2a940 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2a950 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2a960 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2a970 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2a980 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2a990 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2a9a0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
2a9b0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2a9c0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
2a9d0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2a9e0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
2a9f0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
2aa00 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
2aa10 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
2aa20 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
2aa30 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
2aa40 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
2aa50 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
2aa60 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
2aa70 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2aa80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2aa90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2aaa0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2aab0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2aac0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2aad0 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
2aae0 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
2aaf0 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
2ab00 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
2ab10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ab20 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2ab30 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2ab40 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2ab50 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2ab60 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2ab70 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2ab80 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2ab90 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2aba0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2abb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2abc0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2abd0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2abe0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2abf0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2ac00 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2ac10 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2ac20 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
2ac30 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2ac40 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2ac50 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2ac60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2ac70 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2ac80 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2ac90 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2aca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2acb0 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
2acc0 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
2acd0 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
2ace0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2acf0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2ad00 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2ad10 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2ad20 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2ad30 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2ad40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2ad50 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  ** aggregate. A 
2ad60 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2ad70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2ad80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2ad90 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2ada0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
2adb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
2adc0 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
2add0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2ade0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2adf0 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
2ae00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2ae10 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2ae20 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2ae30 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2ae40 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
2ae50 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
2ae60 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
2ae70 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2ae80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2ae90 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2aea0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
2aeb0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2aec0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  cks..**.** It is
2aed0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2aee0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2aef0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2af00 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2af10 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2af20 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2af30 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2af40 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2af50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2af60 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2af70 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2af80 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
2af90 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2afa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
2afb0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
2afc0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
2afd0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
2afe0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
2aff0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2b000 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20  .**.** {F16103} 
2b010 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2b020 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2b030 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61  ] interface beha
2b040 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20  ves exactly.**  
2b050 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71          like [sq
2b060 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b070 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72  ction()] in ever
2b080 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2b090 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2b0a0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2b0b0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72  zFunctionName ar
2b0c0 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74  gument as zero-t
2b0d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
2b0e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74  .**          nat
2b0f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2b100 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72  nstead of as zer
2b110 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2b120 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30  -8..**.** {F1610
2b130 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
2b140 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2b150 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2b160 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b170 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2b180 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
2b190 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
2b1a0 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2b1b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2b1c0 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ons in the [data
2b1d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b1e0 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2b1f0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2b200 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b210 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2b220 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2b230 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2b240 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2b250 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2b260 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 39  E..**.** {F16109
2b270 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2b280 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b290 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b2a0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2b2b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2b2c0 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c  places the P, F,
2b2d0 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73   S, and L values
2b2e0 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20   from any prior 
2b2f0 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  calls with.**   
2b300 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2b310 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76  D, X, N, and E v
2b320 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alues..**.** {F1
2b330 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6112} The [sqlit
2b340 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b350 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  on(D,X,...)] int
2b360 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2b370 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  h.**          a 
2b380 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
2b390 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2b3a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b3b0 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20  n name X is.**  
2b3c0 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74          longer t
2b3d0 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78  han 255 bytes ex
2b3e0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2b3f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2b400 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20 45  **.** {F16118} E
2b410 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 20  ither F must be 
2b420 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2b430 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2b440 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20   else F.**      
2b450 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20      is non-NULL 
2b460 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2b470 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a  NULL, otherwise.
2b480 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2b490 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b4a0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2b4b0 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b  ,S,L)] returns [
2b4c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a  SQLITE_ERROR]..*
2b4d0 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54 68  *.** {F16121} Th
2b4e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2b4f0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e  e_function(D,...
2b500 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2b510 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2b520 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2b530 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53  e of [SQLITE_BUS
2b540 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73  Y] if there exis
2b550 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2b560 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20  ements].**      
2b570 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77      associated w
2b580 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2b590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
2b5a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d 20  .**.** {F16124} 
2b5b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2b5c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2b5d0 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,N,...)] interfa
2b5e0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
2b5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
2b600 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2b610 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72  TE_ERROR] if par
2b620 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 66  ameter N (specif
2b630 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a  ying the number.
2b640 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2b650 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2b660 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  SQL function bei
2b670 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20 69  ng registered) i
2b680 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  s less.**       
2b690 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72     than -1 or gr
2b6a0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a  eater than 127..
2b6b0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20 57  **.** {F16127} W
2b6c0 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67  hen N is non-neg
2b6d0 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69  ative, the [sqli
2b6e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b6f0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2b700 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2b710 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2b720 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2b730 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
2b740 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2b750 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2b760 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2b770 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2b780 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2b790 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2b7a0 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2b7b0 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  F16130} When N i
2b7c0 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2b7d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b7e0 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2b7f0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2b800 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
2b810 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2b820 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20  ked for the SQL 
2b830 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2b840 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74       named X wit
2b850 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  h any number of 
2b860 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2b870 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20 63   {F16133} When c
2b880 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2b890 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b8a0 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2b8b0 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2b8c0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2b8d0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2b8e0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2b8f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2b900 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d   when one implem
2b910 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d  entation has N>=
2b920 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  0 and the other 
2b930 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20  has N=(-1).**   
2b940 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65         the imple
2b950 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2b960 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70   non-zero N is p
2b970 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2b980 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {F16136} When ca
2b990 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2b9a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b9b0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2b9c0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2b9d0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2b9e0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2b9f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2ba00 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2ba10 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2ba20 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ba30 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2ba40 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2ba50 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2ba60 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2ba70 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2ba80 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2ba90 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2baa0 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65  ncoding is prefe
2bab0 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
2bac0 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72  139} For an aggr
2bad0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2bae0 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  on created using
2baf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2bb00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bb10 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2bb20 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61  0,S,L)] the fina
2bb30 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  lizer.**        
2bb40 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c    function L wil
2bb50 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f  l always be invo
2bb60 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  ked exactly once
2bb70 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
2bb80 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f      step functio
2bb90 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  n S is called on
2bba0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2bbb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32 7d 20  .**.** {F16142} 
2bbc0 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
2bbd0 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78  kes either the x
2bbe0 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75  Func or xStep fu
2bbf0 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  nction of.**    
2bc00 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61        an applica
2bc10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2bc20 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2bc30 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a  regate created.*
2bc40 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
2bc50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bc60 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71  nction()] or [sq
2bc70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bc80 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  ction16()],.**  
2bc90 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
2bca0 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74   array of [sqlit
2bcb0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2bcc0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  s passed as the.
2bcd0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72  **          thir
2bce0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2bcf0 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65  always [protecte
2bd00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2bd10 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2bd20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2bd30 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2bd40 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2bd50 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2bd60 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2bd70 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2bd80 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2bd90 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2bda0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2bdb0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2bdc0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2bdd0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2bde0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2bdf0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2be00 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2be10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2be20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2be30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2be40 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2be50 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2be60 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2be70 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2be80 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2be90 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2bea0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2beb0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2bec0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2bed0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2bee0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2bef0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2bf00 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2bf10 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2bf20 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2bf30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2bf40 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31  xt Encodings {F1
2bf50 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0267}.**.** Thes
2bf60 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2bf70 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2bf80 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2bf90 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2bfa0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2bfb0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2bfc0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2bfd0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2bfe0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2bff0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2c000 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2c010 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2c020 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2c030 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2c040 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2c050 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2c060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2c070 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2c080 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2c090 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c0a0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2c0b0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2c0c0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2c0d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2c0e0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2c0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c100 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74  : Obsolete Funct
2c110 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
2c120 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61   functions are a
2c130 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e  ll now obsolete.
2c140 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2c150 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2c160 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2c170 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2c180 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74  e, we continue t
2c190 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65  o support.** the
2c1a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48  se functions.  H
2c1b0 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65  owever, new deve
2c1c0 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73  lopment projects
2c1d0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2c1e0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2c1f0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2c200 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2c210 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2c220 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2c230 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2c240 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2c250 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79  ll you want they
2c260 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69   do..*/.int sqli
2c270 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2c280 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2c290 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ext*);.int sqlit
2c2a0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2c2b0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
2c2c0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2c2d0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2c2e0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2c2f0 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
2c300 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2c310 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73  er(void);.void s
2c320 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2c330 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74  eanup(void);.int
2c340 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2c350 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2c360 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2c370 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2c380 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a  ite3_int64);../*
2c390 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2c3a0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2c3b0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2c3c0 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a  alues {F15100}.*
2c3d0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2c3e0 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2c3f0 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2c400 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2c410 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2c420 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2c430 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2c440 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2c450 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2c460 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2c470 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2c480 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2c490 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2c4a0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2c4b0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2c4c0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2c4d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c4e0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2c4f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c500 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2c510 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2c520 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2c530 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2c540 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2c550 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2c560 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2c570 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2c580 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2c590 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2c5a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c5b0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2c5c0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2c5d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2c5e0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2c5f0 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2c600 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2c610 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2c620 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2c630 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2c640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c650 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2c660 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2c670 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2c680 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c690 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2c6a0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2c6b0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2c6c0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2c6d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c6e0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2c6f0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2c700 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2c710 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2c720 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
2c730 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
2c740 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
2c750 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
2c760 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
2c770 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
2c780 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
2c790 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c7a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
2c7b0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
2c7c0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
2c7d0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
2c7e0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
2c7f0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
2c800 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
2c810 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2c820 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2c830 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2c840 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2c850 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2c860 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2c870 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2c880 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
2c890 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
2c8a0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
2c8b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
2c8c0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
2c8d0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
2c8e0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
2c8f0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2c900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2c910 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2c920 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2c930 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2c940 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2c950 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2c960 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2c970 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2c980 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2c990 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2c9a0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2c9b0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2c9c0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2c9d0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2c9e0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2c9f0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2ca00 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2ca10 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2ca20 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2ca30 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2ca40 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2ca50 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2ca60 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2ca70 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2ca80 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2ca90 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2caa0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2cab0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2cac0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2cad0 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
2cae0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2caf0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2cb00 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2cb10 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2cb20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2cb30 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2cb40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cb50 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2cb60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2cb70 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2cb80 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2cb90 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2cba0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2cbb0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2cbc0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2cbd0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2cbe0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2cbf0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2cc00 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2cc10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2cc20 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2cc30 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2cc40 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2cc50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2cc60 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2cc70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2cc80 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
2cc90 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2cca0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54  **.** {F15103} T
2ccb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2ccc0 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2ccd0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2cce0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2ccf0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2cd00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2cd10 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2cd20 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2cd30 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e    returns a poin
2cd40 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2cd50 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2cd60 2a 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b  * {F15106} The [
2cd70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2cd80 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2cd90 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2cda0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2cdb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2cdc0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2cdd0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2cde0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2cdf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2ce00 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2ce10 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2ce20 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2ce30 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2ce40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2ce50 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2ce60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ce70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ce80 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
2ce90 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2cea0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2ceb0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2cec0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2ced0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2cee0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2cef0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2cf00 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2cf10 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2cf20 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2cf30 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2cf40 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2cf50 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2cf60 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2cf70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2cf80 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2cf90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cfa0 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cfc0 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2cfd0 0a 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65  .** {F15112} The
2cfe0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cff0 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2d000 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d020 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d030 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d040 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2d050 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2d060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d070 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2d080 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2d090 20 7b 46 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {F15115} The [s
2d0a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d0b0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2d0c0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2d0d0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2d0e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d0f0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2d100 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2d110 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2d120 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2d130 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2d140 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2d150 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38  r..**.** {F15118
2d160 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d170 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2d180 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d190 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d1a0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d1b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d1c0 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2d1d0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2d1e0 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2d1f0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2d200 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2d210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d  ..**.** {F15121}
2d220 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d230 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2d240 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2d250 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d260 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d270 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d280 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2d290 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
2d2a0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2d2b0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2d2c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2d2d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2d2e0 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F15124} The [sql
2d2f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d300 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2d310 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2d320 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2d330 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d340 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2d350 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2d360 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2d370 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2d380 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2d390 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2d3a0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2d3b0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2d3c0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2d3d0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54  **.** {F15127} T
2d3e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d3f0 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
2d400 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d410 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d420 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d430 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d440 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2d450 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2d460 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2d470 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
2d480 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
2d490 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2d4a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2d4b0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2d4c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d  ..**.** {F15130}
2d4d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d4e0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2d4f0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2d500 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2d510 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2d520 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d530 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2d540 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2d550 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2d560 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2d570 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2d580 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2d590 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2d5a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2d5b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
2d5c0 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
2d5d0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
2d5e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2d5f0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2d600 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2d610 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2d620 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2d630 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2d640 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2d650 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2d660 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2d670 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2d680 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2d690 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
2d6a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20  .**.** {F15136} 
2d6b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2d6c0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2d6d0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2d6e0 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
2d6f0 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
2d700 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d710 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
2d720 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
2d730 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2d740 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2d750 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
2d760 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
2d770 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
2d780 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
2d790 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
2d7a0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2d7b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2d7c0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
2d7d0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2d7e0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2d7f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
2d800 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
2d810 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74  ppropriate for t
2d820 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2d830 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d840 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2d850 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
2d860 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
2d870 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2d880 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2d890 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
2d8a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2d8b0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2d8c0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2d8d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d8e0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
2d8f0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
2d900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2d910 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2d920 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2d930 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2d940 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
2d950 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2d960 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
2d970 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2d980 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2d990 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2d9a0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2d9b0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2d9c0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2d9d0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d9e0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2d9f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2da00 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
2da10 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2da20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2da30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2da40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2da50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2da60 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
2da70 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2da80 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2da90 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2daa0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2dab0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2dac0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2dad0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36  ion Context {F16
2dae0 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  210}.**.** The i
2daf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2db00 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2db10 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2db20 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
2db30 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
2db40 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
2db50 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
2db60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
2db70 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2db80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2db90 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
2dba0 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61  lled for a.** pa
2dbb0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2dbc0 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
2dbd0 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
2dbe0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2dbf0 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79  t that.** memory
2dc00 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
2dc10 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f  pointer to it. O
2dc20 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2dc30 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2dc40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2dc50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2dc60 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2dc70 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2dc80 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61  index,.** the sa
2dc90 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2dca0 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65  urned. The imple
2dcb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2dcc0 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
2dcd0 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  se.** the return
2dce0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
2dcf0 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
2dd00 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  .** SQLite autom
2dd10 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2dd20 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
2dd30 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
2dd40 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
2dd50 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2dd60 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2dd70 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
2dd80 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2dd90 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2dda0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2ddb0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2ddc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2ddd0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
2dde0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2ddf0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2de00 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2de10 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2de20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2de30 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2de40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2de50 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2de60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2de70 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2de80 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2de90 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  TS:.**.** {F1621
2dea0 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76  1} The first inv
2deb0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
2dec0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2ded0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a  ntext(C,N)] for.
2dee0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61  **          a pa
2def0 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
2df00 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74  e of an aggregat
2df10 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20  e function (for 
2df20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
2df30 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2df40 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74   C) causes SQLit
2df50 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20  e to allocate N 
2df60 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c  bytes of memory,
2df70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2df80 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  o that memory, a
2df90 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
2dfa0 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63  ter to the alloc
2dfb0 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a  ated memory..**.
2dfc0 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66 20 61  ** {F16213} If a
2dfd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2dfe0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2dff0 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  during.**       
2e000 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
2e010 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2e020 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e  N)] then the fun
2e030 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e  ction returns 0.
2e040 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20  .**.** {F16215} 
2e050 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  Second and subse
2e060 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2e070 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
2e080 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2e090 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2e0a0 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63  ] for the same c
2e0b0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43  ontext pointer C
2e0c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e  .**          ign
2e0d0 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ore the N parame
2e0e0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ter and return a
2e0f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2e100 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2e110 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
2e120 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2e130 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
2e140 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37  n..**.** {F16217
2e150 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
2e160 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  ocated by [sqlit
2e170 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e180 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a  text(C,N)] is.**
2e190 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61            automa
2e1a0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e  tically freed on
2e1b0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2e1c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2e1d0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
2e1e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2e1f0 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20  lize()] for the 
2e200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e210 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ent] containing.
2e220 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2e230 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2e240 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
2e250 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f  th context C..*/
2e260 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
2e270 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e280 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e290 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
2e2a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e2b0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
2e2c0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30  unctions {F16240
2e2d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
2e2e0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
2e2f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e300 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2e310 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
2e320 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
2e330 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
2e340 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
2e350 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
2e360 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e370 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
2e380 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e390 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
2e3a0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
2e3b0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
2e3c0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2e3d0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2e3e0 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  on. {END}.**.** 
2e3f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2e400 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2e410 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2e420 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2e430 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e440 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2e450 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2e460 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2e470 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b  * {F16243} The [
2e480 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2e490 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  a(C)] interface 
2e4a0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2e4b0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2e4c0 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    P pointer from
2e4d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2e4e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2e4f0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2e500 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2e510 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e520 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
2e530 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
2e540 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2e550 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
2e560 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
2e570 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73  sociated with [s
2e580 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2e590 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  C..*/.void *sqli
2e5a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
2e5b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2e5c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e5d0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2e5e0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
2e5f0 6f 6e 73 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a  ons {F16250}.**.
2e600 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
2e610 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2e620 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2e630 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
2e640 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
2e650 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2e660 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
2e670 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
2e680 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2e690 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e6a0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2e6b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e6c0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2e6d0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2e6e0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2e6f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e700 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2e710 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
2e720 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
2e730 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
2e740 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2e750 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  le(C)] interface
2e760 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2e770 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2e780 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f     D pointer fro
2e790 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
2e7a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2e7b0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2e7c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2e7d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e7e0 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
2e7f0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
2e800 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
2e810 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
2e820 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
2e830 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
2e840 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
2e850 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a   C..*/.sqlite3 *
2e860 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2e870 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2e880 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2e890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2e8a0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
2e8b0 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a   Data {F16270}.*
2e8c0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2e8d0 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2e8e0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2e8f0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2e900 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2e910 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2e920 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2e930 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2e940 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2e950 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2e960 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2e970 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2e980 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2e990 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2e9a0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2e9b0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2e9c0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2e9d0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2e9e0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2e9f0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2ea00 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2ea10 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2ea20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2ea30 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2ea40 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2ea50 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2ea60 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2ea70 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2ea80 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2ea90 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2eaa0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2eab0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2eac0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2ead0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2eae0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2eaf0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2eb00 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2eb10 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2eb20 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2eb30 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2eb40 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2eb50 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2eb60 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2eb70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2eb80 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
2eb90 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2eba0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2ebb0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2ebc0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2ebd0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2ebe0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2ebf0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2ec00 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2ec10 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2ec20 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2ec30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ec40 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
2ec50 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2ec60 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2ec70 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2ec80 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2ec90 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2eca0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2ecb0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2ecc0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2ecd0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2ece0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2ecf0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2ed00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2ed10 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2ed20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2ed30 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2ed40 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2ed50 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2ed60 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
2ed70 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2ed80 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2ed90 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
2eda0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
2edb0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
2edc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2edd0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
2ede0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
2edf0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2ee00 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2ee10 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2ee20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2ee30 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
2ee40 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
2ee50 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2ee60 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2ee70 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2ee80 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2ee90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2eea0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2eeb0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2eec0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2eed0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2eee0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2eef0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2ef00 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2ef10 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2ef20 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2ef30 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2ef40 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2ef50 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2ef60 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2ef70 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2ef80 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2ef90 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2efa0 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
2efb0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2efc0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2efd0 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2efe0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2eff0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2f000 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
2f010 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2f020 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2f030 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2f040 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2f050 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2f060 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2f070 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2f080 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2f090 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2f0a0 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
2f0b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f0c0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2f0d0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2f0e0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2f0f0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2f100 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2f110 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2f120 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32  S:.**.** {F16272
2f130 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
2f140 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
2f150 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f160 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2f170 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
2f180 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2f190 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
2f1a0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2f1b0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2f1c0 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
2f1d0 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
2f1e0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
2f1f0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2f200 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
2f210 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
2f220 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
2f230 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
2f240 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2f250 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
2f260 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
2f270 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
2f280 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
2f290 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2f2a0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2f2b0 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
2f2c0 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  t C..**.** {F162
2f2d0 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
2f2e0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2f2f0 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
2f300 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
2f310 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
2f320 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
2f330 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
2f340 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
2f350 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2f360 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f370 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
2f380 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
2f390 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
2f3a0 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
2f3b0 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51  *.** {F16277} SQ
2f3c0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2f3d0 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
2f3e0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2f3f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
2f400 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
2f410 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
2f420 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
2f430 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20  .**.** {F16278} 
2f440 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
2f450 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2f460 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
2f470 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2f480 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
2f490 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
2f4a0 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
2f4b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2f4c0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2f4d0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2f4e0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
2f4f0 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  r N..**.** {F162
2f500 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
2f510 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
2f520 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
2f530 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
2f540 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
2f550 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
2f560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f570 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
2f580 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2f590 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
2f5a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f5b0 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
2f5c0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2f5d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2f5e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f5f0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2f600 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2f610 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2f620 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2f630 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2f640 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2f650 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2f660 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2f670 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2f680 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a  vior {F10280}.**
2f690 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
2f6a0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
2f6b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2f6c0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
2f6d0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
2f6e0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
2f6f0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2f700 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2f710 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
2f720 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2f730 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2f740 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2f750 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2f760 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2f770 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2f780 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2f790 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2f7a0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2f7b0 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
2f7c0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2f7d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2f7e0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2f7f0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2f800 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2f810 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2f820 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2f830 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2f840 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2f850 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2f860 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2f870 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2f880 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2f890 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2f8a0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2f8b0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2f8c0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2f8d0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2f8e0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2f8f0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2f900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2f910 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2f920 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2f930 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2f940 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2f950 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2f960 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2f970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f980 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2f990 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2f9a0 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a  nction {F16400}.
2f9b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f9c0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
2f9d0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
2f9e0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
2f9f0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
2fa00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2fa10 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
2fa20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
2fa30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2fa40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2fa50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fa60 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
2fa70 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2fa80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
2fa90 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
2faa0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
2fab0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
2fac0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
2fad0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
2fae0 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
2faf0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2fb00 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2fb10 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2fb20 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
2fb30 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
2fb40 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2fb50 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2fb60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2fb70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2fb80 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
2fb90 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2fba0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
2fbb0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fbc0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2fbd0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
2fbe0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
2fbf0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
2fc00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
2fc10 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
2fc20 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
2fc30 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
2fc40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2fc50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2fc60 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
2fc70 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
2fc80 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2fc90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fca0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2fcb0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
2fcc0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
2fcd0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
2fce0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
2fcf0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
2fd00 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
2fd10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2fd20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2fd30 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
2fd40 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2fd50 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2fd60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2fd70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2fd80 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
2fd90 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
2fda0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
2fdb0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2fdc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2fdd0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2fde0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fdf0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2fe00 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2fe10 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2fe20 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2fe30 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2fe40 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
2fe50 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2fe60 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2fe70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2fe80 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2fe90 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2fea0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2feb0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2fec0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2fed0 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
2fee0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2fef0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2ff00 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2ff10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ff20 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51  r() as UTF-8. SQ
2ff30 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2ff40 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2ff50 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2ff60 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2ff70 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
2ff80 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
2ff90 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2ffa0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2ffb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2ffc0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2ffd0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2ffe0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
2fff0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
30000 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
30010 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
30020 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
30030 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
30040 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
30050 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
30060 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30070 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
30080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30090 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
300a0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
300b0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
300c0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
300d0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
300e0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
300f0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
30100 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
30110 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30120 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
30130 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30140 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
30150 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
30160 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
30170 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
30180 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
30190 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
301a0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
301b0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
301c0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
301d0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
301e0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
301f0 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
30200 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30210 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
30220 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
30230 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
30240 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
30250 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
30260 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
30270 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
30280 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
30290 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
302a0 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
302b0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
302c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
302d0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
302e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
302f0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
30300 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
30310 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
30320 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30330 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
30340 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
30350 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
30360 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
30370 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
30380 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
30390 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
303a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
303b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
303c0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
303d0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
303e0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
303f0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
30400 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
30410 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
30420 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30430 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
30440 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
30450 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
30460 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
30470 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30480 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
30490 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
304a0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
304b0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
304c0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  gument..** The s
304d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
304e0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
304f0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
30500 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
30510 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30520 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30530 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
30540 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
30550 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
30560 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
30570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30580 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
30590 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
305a0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
305b0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
305c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
305d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
305e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  LL..**.** The sq
305f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30600 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
30610 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
30620 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30630 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
30640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30650 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
30660 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
30670 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30680 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30690 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
306a0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
306b0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
306c0 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
306d0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
306e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
306f0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
30700 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
30710 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
30720 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
30730 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
30740 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
30750 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
30760 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
30770 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
30780 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
30790 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
307a0 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
307b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
307c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
307d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
307e0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
307f0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
30800 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
30810 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
30820 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
30830 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
30840 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
30850 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
30860 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
30870 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30880 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
30890 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
308a0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
308b0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
308c0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
308d0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
308e0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
308f0 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
30900 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30910 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
30920 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
30930 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
30940 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30950 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30960 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
30970 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
30980 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
30990 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
309a0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
309b0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
309c0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
309d0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
309e0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
309f0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
30a00 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
30a10 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
30a20 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
30a30 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
30a40 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
30a50 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c  rfaces or.** sql
30a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
30a70 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
30a80 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
30a90 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
30aa0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
30ab0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
30ac0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
30ad0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
30ae0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
30af0 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20   copy the it or 
30b00 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
30b10 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
30b20 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
30b30 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
30b40 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
30b50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
30b60 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
30b70 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
30b80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30b90 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
30ba0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
30bb0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
30bc0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
30bd0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
30be0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
30bf0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
30c00 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
30c10 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
30c20 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
30c30 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30c40 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
30c50 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30c60 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
30c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30c80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30c90 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
30ca0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
30cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30cc0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
30cd0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
30ce0 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
30cf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
30d00 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
30d10 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
30d20 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30d30 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
30d40 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30d50 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
30d60 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
30d70 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
30d80 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
30d90 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
30da0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
30db0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
30dc0 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
30dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30de0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
30df0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
30e00 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
30e10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30e20 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
30e30 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
30e40 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
30e50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30e60 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
30e70 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
30e80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
30e90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
30ea0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
30eb0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
30ec0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
30ed0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
30ee0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30ef0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30f00 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
30f10 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
30f20 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
30f30 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
30f40 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
30f50 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
30f60 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68  *.** {F16403} Th
30f70 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e  e default return
30f80 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20   value from any 
30f90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30fa0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  NULL..**.** {F16
30fb0 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  406} The [sqlite
30fc0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
30fd0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
30fe0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30ff0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
31000 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
31010 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f  on C to be a BLO
31020 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65  B that is N byte
31030 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  s.**          in
31040 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68   length and with
31050 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64   content pointed
31060 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20   to by V..**.** 
31070 7b 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71  {F16409} The [sq
31080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
31090 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  ble(C,V)] interf
310a0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
310b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
310c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
310d0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
310e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
310f0 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
31100 46 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c  F16412} The [sql
31110 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31120 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  r(C,V,N)] interf
31130 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
31140 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
31150 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
31160 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
31170 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
31180 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
31190 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
311a0 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38  ROR] and a UTF-8
311b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
311c0 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
311d0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
311e0 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
311f0 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
31200 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
31210 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
31220 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68  *.** {F16415} Th
31230 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31240 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
31250 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31260 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
31270 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
31280 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
31290 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
312a0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
312b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
312c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
312d0 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65   a UTF-16 native
312e0 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f   byte order erro
312f0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
31300 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f        copied fro
31310 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  m V up to the fi
31320 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
31330 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  tor or until N b
31340 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
31350 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
31360 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
31370 2a 20 7b 46 31 36 34 31 38 7d 20 54 68 65 20 5b  * {F16418} The [
31380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31390 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20  rror_toobig(C)] 
313a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
313b0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
313c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
313d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
313e0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
313f0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
31400 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
31410 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
31420 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
31430 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
31440 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d  ..**.** {F16421}
31450 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31460 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
31470 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
31480 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
31490 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
314a0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
314b0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
314c0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
314d0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
314e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d       [SQLITE_NOM
314f0 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  EM] and an appro
31500 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
31510 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
31520 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  424} The [sqlite
31530 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
31540 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66  ode(C,E)] interf
31550 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
31560 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
31570 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
31580 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31590 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
315a0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e  th error code E.
315b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65  .**          The
315c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
315d0 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ext is unchanged
315e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d  ..**.** {F16427}
315f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31600 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69  sult_int(C,V)] i
31610 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31620 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31630 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
31640 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31650 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74  e the 32-bit int
31660 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
31670 0a 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54 68 65  .** {F16430} The
31680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31690 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74  _int64(C,V)] int
316a0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
316b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
316c0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
316d0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
316e0 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67  the 64-bit integ
316f0 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
31700 2a 20 7b 46 31 36 34 33 33 7d 20 54 68 65 20 5b  * {F16433} The [
31710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31720 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ull(C)] interfac
31730 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
31740 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
31750 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
31760 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  on C to be NULL.
31770 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20  .**.** {F16436} 
31780 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31790 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
317a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
317b0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
317c0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
317d0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
317e0 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20  to be the UTF-8 
317f0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
31800 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66     V up to the f
31810 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
31820 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
31830 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
31840 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
31850 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
31860 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
31870 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6439} The [sqlit
31880 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31890 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
318a0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
318b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
318c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
318d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
318e0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
318f0 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
31900 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
31910 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
31920 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
31930 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
31940 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
31950 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
31960 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
31970 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d  ..**.** {F16442}
31980 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31990 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
319a0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
319b0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
319c0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
319d0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
319e0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
319f0 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
31a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
31a10 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
31a20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
31a30 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
31a40 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
31a50 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20  irst N bytes or 
31a60 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
31a70 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
31a80 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  16445} The [sqli
31a90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31aa0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6le(C,V,N,D)] in
31ab0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31ac0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31ad0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31ae0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31af0 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74   the UTF-16 litt
31b00 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
31b10 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
31b20 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
31b30 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
31b40 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
31b50 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
31b60 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
31b70 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
31b80 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20  .**.** {F16448} 
31b90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31ba0 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20  ult_value(C,V)] 
31bb0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
31bc0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
31bd0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
31be0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
31bf0 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  be the [unprotec
31c00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31c10 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
31c20 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
31c30 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16451} The [sql
31c40 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
31c50 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
31c60 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
31c80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
31c90 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
31ca0 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20   N-byte BLOB of 
31cb0 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
31cc0 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {F16454} The [s
31cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31ce0 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
31cf0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31d00 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
31d10 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
31d20 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
31d30 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
31d40 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
31d50 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
31d60 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ning..**.** {F16
31d70 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
31d80 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
31d90 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
31da0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
31db0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
31dc0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
31dd0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
31de0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
31df0 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
31e00 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
31e10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31e20 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
31e30 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
31e40 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
31e50 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
31e60 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
31e70 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
31e80 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
31e90 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
31ea0 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
31eb0 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
31ec0 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
31ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
31ee0 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
31ef0 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
31f00 46 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  F16460} If the D
31f10 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
31f20 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
31f30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
31f40 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
31f50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
31f60 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
31f70 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
31f80 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
31f90 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
31fa0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
31fb0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
31fc0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
31fd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
31fe0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
31ff0 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
32000 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
32010 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
32020 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
32030 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
32040 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
32050 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
32060 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
32070 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
32080 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66  *.** {F16463} If
32090 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
320a0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
320b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
320c0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
320d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
320e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
320f0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
32100 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32110 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
32120 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32130 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
32140 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
32150 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
32160 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32170 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
32180 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
32190 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
321a0 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
321b0 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
321c0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
321d0 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a  ANSIENT] then.**
321e0 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
321f0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
32200 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
32210 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
32220 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
32230 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
32240 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
32250 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
32260 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32270 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
32280 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32290 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
322a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
322b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
322c0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
322d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
322e0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
322f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
32300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32310 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
32320 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32330 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
32340 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32350 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32360 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32370 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
32380 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
32390 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
323a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
323b0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
323c0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
323d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
323e0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
323f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
32400 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32410 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
32420 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
32430 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32440 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
32450 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
32460 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
32470 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32480 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
32490 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
324a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
324b0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
324c0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
324d0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
324e0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
324f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32500 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
32510 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
32520 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
32530 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
32540 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32550 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
32560 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
32570 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
32580 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
325a0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
325b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
325c0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
325d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
325e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
325f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
32600 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
32610 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
32620 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
32630 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
32640 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
32650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
32660 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
32670 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46  ing Sequences {F
32680 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16600}.**.** The
32690 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
326a0 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
326b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
326c0 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
326d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
326e0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
326f0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
32700 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
32710 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
32720 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32730 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
32740 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
32750 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
32760 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32770 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
32780 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32790 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
327a0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
327b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
327c0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
327d0 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
327e0 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
327f0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
32800 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
32810 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
32820 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
32830 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
32840 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
32850 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
32860 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
32870 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
32880 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
32890 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
328a0 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
328b0 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
328c0 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
328d0 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
328e0 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
328f0 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
32900 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
32910 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
32920 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
32930 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
32940 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
32950 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
32960 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
32970 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
32980 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
32990 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
329a0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
329b0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
329c0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
329d0 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
329e0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
329f0 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
32a00 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
32a10 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
32a20 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
32a30 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
32a40 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
32a50 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
32a60 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
32a70 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
32a80 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
32a90 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
32aa0 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
32ab0 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
32ac0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
32ad0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
32ae0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
32af0 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
32b00 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
32b10 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
32b20 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
32b30 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
32b40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
32b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32b60 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
32b70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32b80 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
32b90 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
32ba0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
32bb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
32bc0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
32bd0 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
32be0 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
32bf0 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
32c00 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
32c10 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
32c20 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
32c30 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
32c40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
32c50 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
32c60 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
32c70 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
32c80 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63  END}  The applic
32c90 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
32ca0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
32cb0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
32cc0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
32cd0 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
32ce0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
32cf0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
32d00 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
32d10 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
32d20 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
32d30 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
32d40 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
32d50 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
32d60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
32d70 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
32d80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32d90 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
32da0 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
32db0 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
32dc0 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
32dd0 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
32de0 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
32df0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
32e00 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
32e10 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
32e20 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
32e30 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
32e40 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
32e50 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
32e60 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
32e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32e80 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
32e90 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
32ea0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
32eb0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
32ec0 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
32ed0 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
32ee0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
32ef0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
32f00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32f10 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
32f20 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
32f30 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
32f40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
32f50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d  :.**.** {F16603}
32f60 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
32f70 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
32f80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
32f90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32fa0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
32fb0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
32fc0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
32fd0 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
32fe0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
32ff0 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
33000 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
33010 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
33020 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
33030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
33040 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
33050 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
33060 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
33070 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69  ** {F16604} SQLi
33080 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
33090 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
330a0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
330b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
330c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
330d0 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
330e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
330f0 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
33100 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
33110 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
33120 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
33130 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
33140 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
33150 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
33160 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
33170 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63  .** {F16606} Suc
33180 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
33190 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
331a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
331b0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
331c0 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
331d0 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
331e0 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
331f0 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
33200 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
33210 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
33220 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 49  **.** {F16609} I
33230 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
33240 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
33250 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33260 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
33270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33280 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
33290 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
332a0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
332b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
332c0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
332d0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
332e0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
332f0 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  F16612} A collat
33300 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33310 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
33320 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
33330 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20  *.** {F16615} A 
33340 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33350 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
33360 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
33370 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
33380 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
33390 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
333a0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
333b0 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {F16618} The poi
333c0 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
333d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
333e0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
333f0 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
33400 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
33410 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
33420 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33430 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
33440 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
33450 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
33460 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
33470 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s of F..**.** {F
33480 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
33490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
334a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
334b0 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
334c0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
334d0 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
334e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
334f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33500 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
33510 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
33520 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
33530 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
33540 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46  **.** {F16624} F
33550 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
33560 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33570 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
33580 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
33590 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
335a0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
335b0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
335c0 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
335d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
335e0 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b  rations on the [
335f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33600 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76  ion] B on text v
33610 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20  alues that.**   
33620 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63         use the c
33630 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
33640 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a  e named X..**.**
33650 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {F16627} The [s
33660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33670 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
33680 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
33690 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
336a0 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
336b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
336c0 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
336d0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
336e0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
336f0 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
33700 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
33710 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
33720 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
33730 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
33740 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d  ..**.** {F16630}
33750 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
33760 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
33770 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
33780 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
33790 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
337a0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
337b0 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
337c0 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
337d0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
337e0 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
337f0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
33800 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
33810 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
33820 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
33830 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
33840 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
33850 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33860 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
33870 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
33880 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
33890 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
338a0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
338b0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
338c0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
338d0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
338e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
338f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33900 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
33910 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33920 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
33930 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
33940 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
33950 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
33960 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
33970 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
33980 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
33990 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
339a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
339b0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
339c0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
339d0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
339e0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
339f0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
33a00 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
33a10 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
33a20 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
33a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
33a40 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
33a50 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30  allbacks {F16700
33a60 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  }.**.** To avoid
33a70 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
33a80 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
33a90 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
33aa0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
33ab0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
33ac0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
33ad0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
33ae0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
33af0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
33b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
33b10 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
33b20 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
33b30 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
33b40 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
33b50 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
33b60 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
33b70 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
33b80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33b90 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
33ba0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
33bb0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
33bc0 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
33bd0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
33be0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
33bf0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
33c00 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {F16703} If sql
33c10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33c20 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
33c30 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
33c40 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
33c50 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
33c60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33c70 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
33c80 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
33c90 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
33ca0 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
33cb0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
33cc0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
33cd0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
33ce0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
33cf0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
33d00 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
33d10 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
33d20 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
33d30 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
33d40 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33d50 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
33d60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
33d70 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
33d80 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
33d90 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
33da0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
33db0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
33dc0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
33dd0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
33de0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
33df0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
33e00 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
33e10 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
33e20 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
33e30 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
33e40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
33e50 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
33e60 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
33e70 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
33e80 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
33e90 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
33ea0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
33eb0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
33ec0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
33ed0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33ee0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
33ef0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
33f00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
33f10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33f20 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
33f30 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
33f40 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73 75  ** {F16702} A su
33f50 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
33f60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
33f70 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46  ion_needed(D,P,F
33f80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
33f90 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  r [sqlite3_colla
33fa0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c  tion_needed16(D,
33fb0 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20  P,F)] causes.** 
33fc0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61           the [da
33fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33fe0 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63  n] D to invoke c
33ff0 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66  allback F with f
34000 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
34010 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
34020 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61  never it needs a
34030 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
34040 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20  tion for a.**   
34050 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
34060 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69   sequence that i
34070 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20  t does not know 
34080 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  about..**.** {F1
34090 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65  6704} Each succe
340a0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
340b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
340c0 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a  _needed()] or.**
340d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
340e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
340f0 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64  ded16()] overrid
34100 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  es the callback 
34110 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
34120 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
34130 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
34140 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f  nection] by prio
34150 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65  r calls to eithe
34160 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
34170 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
34180 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65  F16706} The name
34190 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65   of the requeste
341a0 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  d collating func
341b0 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74  tion passed in t
341c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34  he.**          4
341d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
341e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
341f0 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20  in UTF-8 if the 
34200 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
34210 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65       was registe
34220 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
34230 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34240 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ded()] and.**   
34250 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46         is in UTF
34260 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
34270 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c  order if the cal
34280 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20  lback was.**    
34290 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
342a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
342b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
342c0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
342d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
342e0 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
342f0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
34300 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
34310 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
34320 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
34330 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
34340 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34350 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
34360 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
34370 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34380 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34390 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
343a0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
343b0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
343c0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
343d0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
343e0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
343f0 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
34400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
34410 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
34420 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
34430 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
34440 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
34450 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
34460 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
34470 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
34480 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
34490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
344a0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
344b0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
344c0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
344d0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
344e0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
344f0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
34500 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
34510 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
34520 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
34530 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
34540 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
34550 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
34560 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
34570 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
34580 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
34590 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
345a0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
345b0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
345c0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
345d0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
345e0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
345f0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
34600 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
34610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
34620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
34630 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
34640 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
34650 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
34660 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
34670 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
34680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34690 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
346a0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
346b0 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a  ime {F10530}.**.
346c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
346d0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
346e0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
346f0 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
34700 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
34710 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
34720 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
34730 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
34740 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
34750 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
34760 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
34770 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
34780 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
34790 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
347a0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
347b0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
347c0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
347d0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
347e0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
347f0 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
34800 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
34810 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
34820 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
34830 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
34840 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
34850 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  d..**.** SQLite 
34860 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
34870 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
34880 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
34890 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
348a0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
348b0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
348c0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
348d0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33  S:.**.** {F10533
348e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
348f0 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
34900 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  ce invokes the x
34910 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20  Sleep.**        
34920 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20    method of the 
34930 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
34940 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64  _vfs|VFS] in ord
34950 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
34960 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74    suspend execut
34970 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
34980 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74  nt thread for at
34990 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20   least.**       
349a0 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64     M millisecond
349b0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36  s..**.** {F10536
349c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
349d0 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
349e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
349f0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
34a00 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64       millisecond
34a10 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
34a20 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66  lly requested of
34a30 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a   the operating.*
34a40 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65  *          syste
34a50 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  m, which might b
34a60 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
34a70 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a  e parameter M..*
34a80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
34a90 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
34aa0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
34ab0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
34ac0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
34ad0 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a  Files {F10310}.*
34ae0 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
34af0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
34b00 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
34b10 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
34b20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
34b30 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
34b40 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
34b50 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
34b60 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
34b70 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
34b80 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
34b90 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
34ba0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
34bb0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
34bc0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
34bd0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
34be0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
34bf0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
34c00 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
34c10 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
34c20 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64   not safe to mod
34c30 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
34c40 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61  e once a [databa
34c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
34c60 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65  * has been opene
34c70 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64  d.  It is intend
34c80 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
34c90 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
34ca0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
34cb0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
34cc0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
34cd0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
34ce0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
34cf0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
34d00 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63  l and remain unc
34d10 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65  hanged thereafte
34d20 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  r..*/.SQLITE_EXT
34d30 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
34d40 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
34d50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34d60 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
34d70 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
34d80 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
34d90 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a   Mode {F12930}.*
34da0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
34db0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
34dc0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34dd0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
34de0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34df0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
34e00 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
34e10 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
34e20 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
34e30 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
34e40 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
34e50 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63  ectively.  Autoc
34e60 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
34e70 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
34e80 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
34e90 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
34ea0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
34eb0 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  nt..** Autocommi
34ec0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
34ed0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
34ee0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
34ef0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
34f00 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
34f10 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
34f20 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
34f30 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
34f40 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
34f50 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
34f60 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
34f70 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
34f80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
34f90 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
34fa0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
34fb0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
34fc0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
34fd0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
34fe0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
34ff0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
35000 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
35010 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
35020 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
35030 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
35040 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
35050 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
35060 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
35070 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
35080 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
35090 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71  {F12931} The [sq
350a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
350b0 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61  mmit(D)] interfa
350c0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
350d0 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ero or.**       
350e0 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b     zero if the [
350f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35100 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20  ion] D is or is 
35110 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
35120 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  t.**          mo
35130 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  de, respectively
35140 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d  ..**.** {F12932}
35150 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
35160 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
35170 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33  t..**.** {F12933
35180 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
35190 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
351a0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42   a successful [B
351b0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
351c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20  .**.** {F12934} 
351d0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
351e0 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20  is enabled by a 
351f0 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d  successful [COMM
35200 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
35210 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  ].**          st
35220 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c  atement..**.** L
35230 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
35240 2a 20 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e  * {A12936} If an
35250 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
35260 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
35270 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
35280 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  e database.**   
35290 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f         connectio
352a0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
352b0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
352c0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
352d0 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
352e0 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e     is undefined.
352f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35300 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
35310 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
35320 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
35330 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
35340 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
35350 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
35360 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  120}.**.** The s
35370 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35390 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
353a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
353b0 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
353c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
353d0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
353e0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61   The database ha
353f0 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79  ndle returned by
35400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  .** sqlite3_db_h
35410 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
35420 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
35430 65 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  e that was the f
35440 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
35450 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
35460 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
35470 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
35480 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
35490 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
354a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
354b0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
354c0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
354d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
354e0 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
354f0 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
35500 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35510 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
35520 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
35530 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35540 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
35550 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ith the.**      
35560 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
35570 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73  atement] S..*/.s
35580 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
35590 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
355a0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
355b0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
355c0 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
355d0 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d statement {F13
355e0 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  140}.**.** This 
355f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35600 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35610 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
35620 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
35630 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
35640 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35660 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
35670 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
35680 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
35690 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
356a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
356b0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
356c0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
356d0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
356e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
356f0 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65   pDb.  If no pre
35700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
35710 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
35720 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
35730 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
35740 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
35750 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
35760 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34 33 7d 20 49  **.** {F13143} I
35770 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
35780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
35790 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72  hat holds one or
357a0 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
357b0 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70    unfinalized [p
357c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
357d0 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e  ts] and S is a N
357e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20  ULL pointer,.** 
357f0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
35800 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
35810 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20  (D, S)] routine 
35820 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70  shall return a p
35830 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
35840 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65     to one of the
35850 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35860 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
35870 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  with D..**.** {F
35880 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61  13146} If D is a
35890 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
358a0 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
358b0 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64  s no unfinalized
358c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
358d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
358e0 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55  s] and S is a NU
358f0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
35900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35910 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35920 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
35930 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55  hall return a NU
35940 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
35950 2a 20 7b 46 31 33 31 34 39 7d 20 49 66 20 53 20  * {F13149} If S 
35960 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
35970 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65  tatement] in the
35980 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35990 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
359a0 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f       and S is no
359b0 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61  t the last prepa
359c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  red statement in
359d0 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   D, then.**     
359e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
359f0 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
35a00 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
35a10 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  urn a pointer.**
35a20 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
35a30 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
35a40 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66  tatement in D af
35a50 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ter S..**.** {F1
35a60 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68  3152} If S is th
35a70 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64  e last [prepared
35a80 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74   statement] in t
35a90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
35aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35ab0 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20  ion] D then the 
35ac0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
35ad0 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20  mt(D, S)].**    
35ae0 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
35af0 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  all return a NUL
35b00 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
35b10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
35b20 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
35b30 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
35b40 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
35b50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35b60 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
35b70 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
35b80 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
35b90 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12950}.**.** The
35ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
35bb0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
35bc0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
35bd0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
35be0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
35bf0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
35c00 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
35c10 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
35c20 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
35c30 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
35c40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
35c50 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
35c60 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
35c70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
35c80 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
35c90 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
35ca0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
35cb0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
35cc0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
35cd0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
35ce0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
35cf0 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
35d00 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
35d10 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
35d20 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
35d30 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
35d40 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
35d50 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
35d60 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
35d70 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
35d80 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
35d90 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
35da0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
35db0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
35dc0 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
35dd0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
35de0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
35df0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
35e00 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
35e10 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
35e20 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
35e30 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
35e40 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
35e50 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67  red, its.** pArg
35e60 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
35e70 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
35e80 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
35e90 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69  .**.** Registeri
35ea0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
35eb0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
35ec0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
35ed0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
35ee0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
35ef0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
35f00 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
35f10 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
35f20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
35f30 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
35f40 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
35f50 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
35f60 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
35f70 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
35f80 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
35f90 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
35fa0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
35fb0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
35fc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
35fd0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
35fe0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
35ff0 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
36000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
36010 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
36020 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
36030 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
36040 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
36050 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
36060 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
36070 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
36080 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
36090 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
360a0 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
360b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
360c0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
360d0 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20  erfaces and are 
360e0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
360f0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
36100 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
36110 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
36120 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
36130 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
36140 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
36150 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
36160 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
36170 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
36180 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
36190 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
361a0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
361b0 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61  mmits on the [da
361c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
361d0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
361e0 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  952} The [sqlite
361f0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
36200 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
36210 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
36220 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
36230 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76     from the prev
36240 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
36250 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
36260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
36270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
36280 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73  NULL on the firs
36290 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72  t call for a par
362a0 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
362b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
362c0 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61  *.** {F12953} Ea
362d0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
362e0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
362f0 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
36300 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
36310 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
36320 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
36330 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d  ..**.** {F12954}
36340 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
36350 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
36360 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
36370 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
36380 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
36390 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
363a0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64  back is canceled
363b0 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
363c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
363d0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
363e0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
363f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ts..**.** {F1295
36400 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
36410 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
36420 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
36430 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
36440 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
36450 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
36460 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
36470 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
36480 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
36490 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
364a0 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
364b0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
364c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
364d0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
364e0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
364f0 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
36500 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
36510 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68  rolls back on th
36520 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36530 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
36540 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73   {F12962} The [s
36550 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36560 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
36570 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
36580 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
36590 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
365a0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
365b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a   with the same.*
365c0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
365d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
365e0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74   D, or NULL on t
365f0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
36600 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
36610 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
36620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
36630 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d  ..**.** {F12963}
36640 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
36650 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36660 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
36670 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
36680 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
36690 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
366a0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
366b0 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61  2964} If the F a
366c0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
366d0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
366e0 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c  k(D,F,P)] is NUL
366f0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
36700 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20  en the rollback 
36710 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
36720 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f   canceled and no
36730 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
36740 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
36750 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
36760 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a  ion rolls back..
36770 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
36780 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
36790 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
367a0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
367b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
367c0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
367d0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
367e0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
367f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
36800 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
36810 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
36820 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12970}.**.** 
36830 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
36840 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
36850 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
36860 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
36870 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
36880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36890 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
368a0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
368b0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
368c0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
368d0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
368e0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
368f0 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
36900 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
36910 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
36920 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
36930 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
36940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36950 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
36960 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
36970 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
36980 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
36990 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
369a0 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
369b0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
369c0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
369d0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
369e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
369f0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
36a00 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
36a10 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
36a20 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36a30 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
36a40 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
36a50 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
36a60 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
36a70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
36a80 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
36a90 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
36aa0 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
36ab0 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
36ac0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
36ad0 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
36ae0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
36af0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
36b00 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
36b10 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
36b20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
36b30 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
36b40 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
36b50 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
36b60 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
36b70 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
36b80 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
36b90 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63  he row. In the c
36ba0 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64  ase of.** an upd
36bb0 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
36bc0 20 72 6f 77 69 64 20 61 66 74 65 72 20 74 68 65   rowid after the
36bd0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
36be0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
36bf0 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
36c00 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
36c10 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
36c20 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
36c30 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
36c40 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
36c50 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
36c60 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
36c70 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
36c80 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
36c90 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
36ca0 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
36cb0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
36cc0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
36cd0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
36ce0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31  S:.**.** {F12971
36cf0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
36d00 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
36d10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  )] interface cau
36d20 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
36d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
36d40 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
36d50 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74  voked with first
36d60 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
36d70 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
36d80 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73    a table row is
36d90 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
36da0 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ted, or deleted 
36db0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  on.**          t
36dc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36dd0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
36de0 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20 5b  * {F12973} The [
36df0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36e00 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
36e10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
36e20 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
36e30 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65      of P for the
36e40 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
36e50 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
36e60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36e70 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   D,.**          
36e80 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20  or NULL for the 
36e90 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  first call..**.*
36ea0 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74 68  * {F12975} If th
36eb0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61  e update hook ca
36ec0 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c  llback F in [sql
36ed0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36ee0 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20  (D,F,P)].**     
36ef0 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65       is NULL the
36f00 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20  n the no update 
36f10 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61  callbacks are ma
36f20 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  de..**.** {F1297
36f30 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  7} Each call to 
36f40 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
36f50 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65  hook(D,F,P)] ove
36f60 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c  rrides prior cal
36f70 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
36f80 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72  o the same inter
36f90 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65  face on the same
36fa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36fb0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
36fc0 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70 64  {F12979} The upd
36fd0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
36fe0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
36ff0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
37000 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ystem.**        
37010 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73    tables such as
37020 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
37030 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
37040 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e  ce are modified.
37050 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20  .**.** {F12981} 
37060 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
37070 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61  eter to the upda
37080 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  te callback.**  
37090 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f          is one o
370a0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
370b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
370c0 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  E] or [SQLITE_UP
370d0 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DATE],.**       
370e0 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20     depending on 
370f0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
37100 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
37110 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76  llback to be inv
37120 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
37130 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 61  983} The third a
37140 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
37150 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
37160 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
37170 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
37180 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
37190 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
371a0 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65 20  s which are the 
371b0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
371c0 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
371d0 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74  e and table that
371e0 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65   is being update
371f0 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20  d...** {F12985} 
37200 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
37210 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
37220 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
37230 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20   row after.**   
37240 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e 67         the chang
37250 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69  e occurs..*/.voi
37260 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
37270 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
37280 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
37290 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
372a0 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
372b0 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
372c0 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
372d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
372e0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
372f0 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
37300 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a  Cache {F10330}.*
37310 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
37320 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72  red cache} {shar
37330 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a  ed cache mode}.*
37340 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
37350 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
37360 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e  ables the sharin
37370 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
37380 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73  e cache.** and s
37390 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63  chema data struc
373a0 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64  tures between [d
373b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
373c0 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  on | connections
373d0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  ].** to the same
373e0 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69   database. Shari
373f0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  ng is enabled if
37400 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
37410 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73   true.** and dis
37420 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
37430 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a  ument is false..
37440 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72  **.** Cache shar
37450 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
37460 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
37470 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
37480 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73  s. {END}.** This
37490 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
374a0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
374b0 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
374c0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
374d0 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
374e0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
374f0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
37500 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
37510 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
37520 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
37530 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
37540 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
37550 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
37560 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
37570 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
37580 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
37590 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
375a0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
375b0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
375c0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
375d0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
375e0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
375f0 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
37600 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
37610 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
37620 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
37630 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
37640 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
37650 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72  ache.  When shar
37660 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
37670 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
37680 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
37690 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
376a0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
376b0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
376c0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
376d0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
376e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
376f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
37700 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
37710 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
37720 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
37730 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
37740 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
37750 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
37760 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63  ..**.** Shared c
37770 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
37780 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
37790 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
377a0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
377b0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
377c0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
377d0 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
377e0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
377f0 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
37800 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
37810 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ly..**.** INVARI
37820 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
37830 33 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  331} A successfu
37840 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
37850 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
37860 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d  shared_cache(B)]
37870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
37880 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  l enable or disa
37890 62 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65  ble shared cache
378a0 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75   mode for any su
378b0 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20  bsequently.**   
378c0 20 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b         created [
378d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
378e0 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65  ion] in the same
378f0 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   process..**.** 
37900 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68  {F10336} When sh
37910 61 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e  ared cache is en
37920 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
37930 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
37940 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
37950 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
37960 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e  always return an
37970 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   error..**.** {F
37980 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  10337} The [sqli
37990 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
379a0 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65  d_cache(B)] inte
379b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
379c0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
379d0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
379e0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
379f0 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75  d or disabled su
37a00 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a  ccessfully..**.*
37a10 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65  * {F10339} Share
37a20 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
37a30 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
37a40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
37a50 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
37a60 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
37a70 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
37a80 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
37a90 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a  emory {F17340}.*
37aa0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
37ab0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37ac0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
37ad0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
37ae0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
37af0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
37b00 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
37b10 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
37b20 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
37b30 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
37b40 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20  library. {END}  
37b50 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
37b60 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
37b70 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
37b80 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
37b90 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
37ba0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
37bb0 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ory..** sqlite3_
37bc0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37bd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
37be0 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
37bf0 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20  ually freed,.** 
37c00 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
37c10 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
37c20 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
37c30 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ested..**.** INV
37c40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
37c50 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F17341} The [sql
37c60 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37c70 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  ory(N)] interfac
37c80 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
37c90 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e            free N
37ca0 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
37cb0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
37cc0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
37cd0 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
37ce0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37cf0 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
37d00 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
37d10 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20  .**.** {F16342} 
37d20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
37d30 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
37d40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
37d50 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
37d60 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
37d70 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69   freed, which mi
37d80 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
37d90 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
37da0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
37db0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e  requested..*/.in
37dc0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
37dd0 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
37de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37df0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
37e00 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37  n Heap Size {F17
37e10 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  350}.**.** The s
37e20 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
37e30 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
37e40 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
37e50 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
37e60 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
37e70 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
37e80 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
37e90 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20  y SQLite..** If 
37ea0 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
37eb0 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
37ec0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
37ed0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
37ee0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
37ef0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37f00 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
37f10 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
37f20 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
37f30 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
37f40 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
37f50 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
37f60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d  d..**.** The lim
37f70 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
37f80 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20  ft", because if 
37f90 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
37fa0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
37fb0 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
37fc0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
37fd0 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
37fe0 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
37ff0 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
38000 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
38010 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
38020 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
38030 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
38040 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  * A negative or 
38050 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
38060 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
38070 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61  e is no soft hea
38080 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b  p limit and.** [
38090 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
380a0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
380b0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
380c0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68  en memory is exh
380d0 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64  austed..** The d
380e0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
380f0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
38100 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
38110 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
38120 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
38130 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
38140 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
38150 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
38160 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
38170 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
38180 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
38190 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
381a0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
381b0 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73  cation.  This is
381c0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
381d0 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73  s.** called a "s
381e0 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
381f0 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
38200 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
38210 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
38220 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
38230 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
38240 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
38250 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
38260 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
38270 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
38280 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
38290 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
382a0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
382b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
382c0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
382d0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
382e0 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
382f0 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c  threads. The val
38300 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
38310 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
38320 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
38330 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
38340 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
38350 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
38360 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20   threads. In.** 
38370 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
38380 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
38390 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
383a0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap usage 
383b0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61  for.** individua
383c0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a  l threads..**.**
383d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
383e0 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20  ** {F16351} The 
383f0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
38400 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74  ap_limit(N)] int
38410 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
38420 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20  soft limit.**   
38430 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65         of N byte
38440 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  s on the amount 
38450 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
38460 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
38470 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
38480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
38490 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
384a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
384b0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a   at any point.**
384c0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d            in tim
384d0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32  e..**.** {F16352
384e0 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
384f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
38500 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
38510 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a  alloc()] would.*
38520 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73 65  *          cause
38530 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e   the total amoun
38540 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d  t of allocated m
38550 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20  emory to exceed 
38560 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
38570 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
38580 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
38590 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
385a0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
385b0 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74          in an at
385c0 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20  tempt to reduce 
385d0 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  the memory usage
385e0 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65   prior to procee
385f0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
38600 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79   with the memory
38610 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65   allocation atte
38620 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  mpt..**.** {F163
38630 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  53} Calls to [sq
38640 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
38650 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
38660 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67  loc()] that trig
38670 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
38680 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75  attempts to redu
38690 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20  ce memory usage 
386a0 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74  through the soft
386b0 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20   heap limit.**  
386c0 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73          mechanis
386d0 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20  m continue even 
386e0 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 74  if the attempt t
386f0 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a  o reduce memory.
38700 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61 67  **          usag
38710 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66 75  e is unsuccessfu
38720 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34  l..**.** {F16354
38730 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  } A negative or 
38740 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
38750 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
38760 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
38770 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
38780 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61  it(N)] means tha
38790 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
387a0 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ft.**          h
387b0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73  eap limit and [s
387c0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
387d0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
387e0 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ly be.**        
387f0 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65    called when me
38800 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65  mory is complete
38810 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  ly exhausted..**
38820 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65  .** {F16355} The
38830 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
38840 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
38850 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
38860 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45  **.** {F16358} E
38870 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
38880 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
38890 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64  imit(N)] overrid
388a0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
388b0 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62 79     values set by
388c0 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73   all prior calls
388d0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
388e0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
388f0 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
38900 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
38910 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
38920 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
38930 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a  ble {F12850}.**.
38940 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
38950 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61  returns metadata
38960 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69