/ Hex Artifact Content
Login

Artifact 2b9e8de3378101ad8ec8de98e3679ad5c2f39427:


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 35 39 20 32 30 30 38 2f 30  n,v 1.359 2008/0
05f0: 36 2f 32 36 20 31 35 3a 30 34 3a 35 38 20 64 72  6/26 15:04:58 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 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ts.</dd>.**.** <
c570: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c580: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
c590: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c5a0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c5b0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c5c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c5d0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
c5e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
c5f0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
c600: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
c610: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
c620: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
c630: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
c640: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
c650: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
c660: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
c670: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
c680: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
c690: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c6a0: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
c6b0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c6c0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c6d0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c6e0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c6f0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
c700: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
c710: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
c720: 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
c730: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
c740: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
c750: 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
c760: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
c770: 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
c780: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68   routines..** Th
c790: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
c7a0: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
c7b0: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
c7c0: 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
c7d0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
c7e0: 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
c7f0: 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
c800: 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
c810: 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
c820: 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
c830: 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a   example.</dd>.*
c840: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c850: 43 4f 4e 46 49 47 5f 4d 45 4d 53 59 53 33 3c 2f  CONFIG_MEMSYS3</
c860: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c870: 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
c880: 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
c890: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c8a0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
c8b0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
c8c0: 33 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  3 symbol defined
c8d0: 2e 20 49 66 20 61 76 61 69 6c 61 62 6c 65 2c 20  . If available, 
c8e0: 74 68 65 6e 20 69 74 20 69 73 20 75 73 65 64 0a  then it is used.
c8f0: 2a 2a 20 74 6f 20 69 6e 73 74 61 6c 6c 20 61 6e  ** to install an
c900: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 73 65 74   alternative set
c910: 20 6f 66 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d   of built-in mem
c920: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c930: 6f 75 74 69 6e 65 73 0a 2a 2a 20 6b 6e 6f 77 6e  outines.** known
c940: 20 61 73 20 74 68 65 20 22 6d 65 6d 73 79 73 33   as the "memsys3
c950: 22 20 61 6c 6c 6f 63 61 74 6f 72 20 28 69 6e 20  " allocator (in 
c960: 74 68 65 20 73 61 6d 65 20 77 61 79 20 61 73 20  the same way as 
c970: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c980: 4c 4c 4f 43 0a 2a 2a 20 6d 61 79 20 62 65 20 75  LLOC.** may be u
c990: 73 65 64 20 74 6f 20 69 6e 73 74 61 6c 6c 20 61  sed to install a
c9a0: 6e 20 65 78 74 65 72 6e 61 6c 20 73 65 74 20 6f  n external set o
c9b0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
c9c0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 29 2e 0a 2a  ion routines)..*
c9d0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 73 20 6d  * This options m
c9e0: 75 73 74 20 62 65 20 70 61 73 73 65 64 20 74 77  ust be passed tw
c9f0: 6f 20 61 72 67 75 6d 65 6e 74 73 2c 20 61 20 70  o arguments, a p
ca00: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6c 61 72 67  ointer to a larg
ca10: 65 20 62 6c 6f 62 20 6f 66 0a 2a 2a 20 61 6c 6c  e blob of.** all
ca20: 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20 28 74  ocated memory (t
ca30: 79 70 65 20 63 68 61 72 2a 29 20 61 6e 64 20 74  ype char*) and t
ca40: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
ca50: 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 69  lock of memory i
ca60: 6e 20 62 79 74 65 73 0a 2a 2a 20 28 74 79 70 65  n bytes.** (type
ca70: 20 69 6e 74 29 2e 20 54 68 65 20 6d 65 6d 73 79   int). The memsy
ca80: 73 33 20 61 6c 6c 6f 63 61 74 6f 72 20 6d 61 6e  s3 allocator man
ca90: 61 67 65 73 20 74 68 69 73 20 62 6c 6f 63 6b 20  ages this block 
caa0: 6f 66 20 6d 65 6d 6f 72 79 20 61 6e 64 20 75 73  of memory and us
cab0: 65 73 0a 2a 2a 20 69 74 20 74 6f 20 73 61 74 69  es.** it to sati
cac0: 73 66 79 20 61 6c 6c 20 72 65 71 75 65 73 74 73  sfy all requests
cad0: 20 66 6f 72 20 64 79 6e 61 6d 69 63 20 6d 65 6d   for dynamic mem
cae0: 6f 72 79 20 6d 61 64 65 20 62 79 20 74 68 65 20  ory made by the 
caf0: 6c 69 62 72 61 72 79 2e 20 54 68 65 0a 2a 2a 20  library. The.** 
cb00: 63 61 6c 6c 65 72 20 6d 75 73 74 20 65 6e 73 75  caller must ensu
cb10: 72 65 20 74 68 61 74 20 74 68 65 20 62 6c 6f 63  re that the bloc
cb20: 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 6d 61  k of memory rema
cb30: 69 6e 73 20 76 61 6c 69 64 20 66 6f 72 20 61 73  ins valid for as
cb40: 20 6c 6f 6e 67 0a 2a 2a 20 61 73 20 74 68 65 20   long.** as the 
cb50: 6d 65 6d 73 79 73 33 20 61 6c 6c 6f 63 61 74 6f  memsys3 allocato
cb60: 72 20 69 73 20 69 6e 20 75 73 65 2e 3c 2f 64 64  r is in use.</dd
cb70: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
cb80: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 59 53  TE_CONFIG_MEMSYS
cb90: 35 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  5</dt>.** <dd>Th
cba0: 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
cbb0: 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
cbc0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
cbd0: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
cbe0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
cbf0: 53 59 53 35 20 73 79 6d 62 6f 6c 20 64 65 66 69  SYS5 symbol defi
cc00: 6e 65 64 2e 20 49 66 20 61 76 61 69 6c 61 62 6c  ned. If availabl
cc10: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 73 69  e, then it is si
cc20: 6d 69 6c 61 72 0a 2a 2a 20 74 6f 20 74 68 65 20  milar.** to the 
cc30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
cc40: 4d 53 59 53 33 20 6f 70 74 69 6f 6e 2e 20 54 68  MSYS3 option. Th
cc50: 65 20 22 6d 65 6d 73 79 73 35 22 20 61 6c 6c 6f  e "memsys5" allo
cc60: 63 61 74 6f 72 20 64 69 66 66 65 72 73 0a 2a 2a  cator differs.**
cc70: 20 66 72 6f 6d 20 74 68 65 20 22 6d 65 6d 73 79   from the "memsy
cc80: 73 33 22 20 61 6c 6c 6f 63 61 74 6f 72 20 69 6e  s3" allocator in
cc90: 20 74 68 61 74 20 69 74 20 72 6f 75 6e 64 73 20   that it rounds 
cca0: 61 6c 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  all allocations 
ccb0: 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 78  up to.** the nex
ccc0: 74 20 6c 61 72 67 65 73 74 20 70 6f 77 65 72 20  t largest power 
ccd0: 6f 66 20 74 77 6f 2e 20 41 6c 74 68 6f 75 67 68  of two. Although
cce0: 20 74 68 69 73 20 69 73 20 73 6f 6d 65 74 69 6d   this is sometim
ccf0: 65 73 20 6d 6f 72 65 20 77 61 73 74 65 66 75 6c  es more wasteful
cd00: 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 70 72 6f  .** than the pro
cd10: 63 65 64 75 72 65 73 20 75 73 65 64 20 62 79 20  cedures used by 
cd20: 6d 65 6d 73 79 73 33 2c 20 69 74 20 67 75 61 72  memsys3, it guar
cd30: 61 6e 74 65 65 73 20 61 6e 20 75 70 70 65 72 20  antees an upper 
cd40: 6c 69 6d 69 74 20 6f 6e 0a 2a 2a 20 69 6e 74 65  limit on.** inte
cd50: 72 6e 61 6c 20 66 72 61 67 6d 65 6e 74 61 74 69  rnal fragmentati
cd60: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  on.</dd>.** </dl
cd70: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
cd80: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
cd90: 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
cda0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
cdb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
cdc0: 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
cdd0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
cde0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
cdf0: 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
ce00: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
ce10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
ce20: 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
ce30: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
ce40: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
ce50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ce60: 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
ce70: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
ce80: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
ce90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
cea0: 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
ceb0: 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
cec0: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
ced0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
cee0: 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
cef0: 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
cf00: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
cf10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cf20: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
cf30: 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
cf40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
cf50: 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
cf60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
cf70: 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
cf80: 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
cf90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
cfa0: 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
cfb0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
cfc0: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
cfd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cfe0: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
cff0: 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
d000: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
d010: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d020: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 59 53  TE_CONFIG_MEMSYS
d030: 33 20 20 20 20 20 20 31 32 20 20 2f 2a 20 75 38  3      12  /* u8
d040: 2a 2c 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  *, int */.#defin
d050: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d060: 4d 45 4d 53 59 53 35 20 20 20 20 20 20 31 33 20  MEMSYS5      13 
d070: 20 2f 2a 20 75 38 2a 2c 20 69 6e 74 20 2a 2f 0a   /* u8*, int */.
d080: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d090: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
d0a0: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
d0b0: 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30 30  lt Codes {F12200
d0c0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
d0d0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
d0e0: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
d0f0: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
d100: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
d110: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
d120: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
d130: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
d140: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
d150: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
d160: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
d170: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
d180: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
d190: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
d1a0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
d1b0: 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20 45 61 63  .** {F12201} Eac
d1c0: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
d1d0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
d1e0: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
d1f0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
d200: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
d210: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
d220: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
d230: 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20 5b  * {F12202} The [
d240: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
d250: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
d260: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
d270: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
d280: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
d290: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
d2a0: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
d2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
d2c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
d2d0: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
d2e0: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
d2f0: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
d300: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
d310: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
d320: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
d330: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
d340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d350: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
d360: 6f 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a  owid {F12220}.**
d370: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
d380: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
d390: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
d3a0: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
d3b0: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
d3c0: 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20  ed the "rowid". 
d3d0: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
d3e0: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
d3f0: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
d400: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
d410: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
d420: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
d430: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
d440: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
d450: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
d460: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
d470: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c  . If.** the tabl
d480: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
d490: 66 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50  f type INTEGER P
d4a0: 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20  RIMARY KEY then 
d4b0: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
d4c0: 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
d4d0: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
d4e0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
d4f0: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f  e returns the ro
d500: 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  wid of the most 
d510: 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
d520: 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f  sful INSERT into
d530: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
d540: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
d550: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
d560: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
d570: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
d580: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73  ccessful INSERTs
d590: 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
d5a0: 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
d5b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d5c0: 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
d5d0: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rned..**.** If a
d5e0: 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20  n INSERT occurs 
d5f0: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
d600: 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64  , then the rowid
d610: 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
d620: 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
d630: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
d640: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
d650: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
d660: 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
d670: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
d680: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
d690: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
d6a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
d6b0: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
d6c0: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
d6d0: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
d6e0: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
d6f0: 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68  .** An INSERT th
d700: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
d710: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
d720: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
d730: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  ** successful IN
d740: 53 45 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f  SERT and does no
d750: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
d760: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
d770: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
d780: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20   Thus INSERT OR 
d790: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
d7a0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
d7b0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
d7c0: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
d7d0: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
d7e0: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
d7f0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
d800: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
d810: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
d820: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45  ails.  When INSE
d830: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
d840: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
d850: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
d860: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
d870: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
d880: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
d890: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
d8a0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
d8b0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
d8c0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
d8d0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
d8e0: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
d8f0: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
d900: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
d910: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
d920: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  face..**.** For 
d930: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
d940: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
d950: 20 49 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69   INSERT is consi
d960: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
d970: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
d980: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
d990: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
d9a0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
d9b0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  TS:.**.** {F1222
d9c0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
d9d0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d9e0: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
d9f0: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a  turns the rowid.
da00: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
da10: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
da20: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
da30: 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68   performed on th
da40: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
da50: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
da60: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74  nection] and wit
da70: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20  hin the same or 
da80: 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20  higher level.** 
da90: 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
daa0: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
dab0: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 20  o if there have 
dac0: 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69  been no qualifyi
dad0: 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a  ng inserts..**.*
dae0: 2a 20 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b  * {F12223} The [
daf0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
db00: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
db10: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
db20: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61  e.**          sa
db30: 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61  me value when ca
db40: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
db50: 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  me trigger conte
db60: 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  xt.**          i
db70: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
db80: 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f  e and after a RO
db90: 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49  LLBACK..**.** LI
dba0: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
dbb0: 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20 73   {A12232} If a s
dbc0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
dbd0: 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e  erforms a new IN
dbe0: 53 45 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65  SERT on the same
dbf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
dc00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
dc10: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
dc20: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
dc30: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20  rowid()].**     
dc40: 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73       function is
dc50: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
dc60: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
dc70: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c  st insert rowid,
dc80: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
dc90: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
dca0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
dcb0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
dcc0: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  id()] is.**     
dcd0: 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62       unpredictab
dce0: 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
dcf0: 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
dd00: 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
dd10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73  .**          las
dd20: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a  t insert rowid..
dd30: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
dd40: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
dd50: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
dd60: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
dd70: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
dd80: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
dd90: 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34 30  Modified {F12240
dda0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  }.**.** This fun
ddb0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
ddc0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
ddd0: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
dde0: 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
ddf0: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
de00: 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
de10: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
de20: 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
de30: 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
de40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
de50: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
de60: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
de70: 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61  ter..** Only cha
de80: 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
de90: 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
dea0: 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
deb0: 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45  UPDATE,.** or DE
dec0: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
ded0: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
dee0: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
def0: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
df00: 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75  gers are not cou
df10: 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  nted. Use the [s
df20: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
df30: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
df40: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
df50: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
df60: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
df70: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
df80: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
df90: 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67  .** A "row chang
dfa0: 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
dfb0: 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
dfc0: 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
dfd0: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
dfe0: 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
dff0: 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
e000: 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
e010: 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
e020: 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
e030: 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
e040: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
e050: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
e060: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
e070: 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20   DROP TABLE, or 
e080: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
e090: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
e0a0: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
e0b0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  t row changes..*
e0c0: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
e0d0: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
e0e0: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
e0f0: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
e100: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
e110: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72  e script of a tr
e120: 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c  igger.  Most SQL
e130: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
e140: 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
e150: 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
e160: 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
e170: 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
e180: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e190: 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
e1a0: 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
e1b0: 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
e1c0: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
e1d0: 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
e1e0: 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
e1f0: 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
e200: 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
e210: 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
e220: 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
e230: 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
e240: 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
e250: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
e260: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
e270: 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
e280: 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
e290: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
e2a0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  xt..**.** This f
e2b0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
e2c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
e2d0: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
e2e0: 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
e2f0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
e300: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
e310: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
e320: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
e330: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
e340: 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20  *.** Thus, when 
e350: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
e360: 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
e370: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e380: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
e390: 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
e3a0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
e3b0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
e3c0: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
e3d0: 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
e3e0: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
e3f0: 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
e400: 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
e410: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
e420: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
e430: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
e440: 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
e450: 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
e460: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
e470: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
e480: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
e490: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
e4a0: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
e4b0: 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
e4c0: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
e4d0: 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
e4e0: 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
e4f0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
e500: 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
e510: 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
e520: 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
e530: 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
e540: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
e550: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
e560: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
e570: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
e580: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
e590: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
e5a0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
e5b0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
e5c0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
e5d0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
e5e0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
e5f0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
e600: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
e610: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
e620: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
e630: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
e640: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
e650: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
e660: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
e670: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
e680: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
e690: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
e6a0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
e6b0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e6c0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
e6d0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
e6e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
e6f0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
e700: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
e710: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
e720: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
e730: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
e740: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
e750: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
e760: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
e770: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
e780: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
e790: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31  S:.**.** {F12241
e7a0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
e7b0: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
e7c0: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
e7d0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
e7e0: 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68            row ch
e7f0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
e800: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
e810: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
e820: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44  **          or D
e830: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
e840: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
e850: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
e860: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
e870: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
e880: 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65  or higher trigge
e890: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
e8a0: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
e8b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
e8c0: 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
e8d0: 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
e8e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 33 7d  ..**.** {F12243}
e8f0: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
e900: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
e910: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
e920: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
e930: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
e940: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62   shall cause sub
e950: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
e960: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
e970: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
e980: 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c   to return zero,
e990: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
e9a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
e9b0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72  umber of rows or
e9c0: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20  iginally in the 
e9d0: 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  table..**.** LIM
e9e0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
e9f0: 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {A12252} If a se
ea00: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
ea10: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
ea20: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
ea30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
ea40: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
ea50: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
ea60: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
ea70: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
ea80: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
ea90: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
eaa0: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
eab0: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
eac0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
ead0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
eae0: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
eaf0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
eb00: 64 69 66 69 65 64 20 7b 46 31 32 32 36 30 7d 0a  dified {F12260}.
eb10: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
eb20: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
eb30: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
eb40: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
eb50: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54  INSERT,.** UPDAT
eb60: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
eb70: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
eb80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eb90: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
eba0: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20  d..** The count 
ebb0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
ebc0: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
ebd0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20  igger contexts. 
ebe0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
ebf0: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
ec00: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
ec10: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
ec20: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
ec30: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
ec40: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
ec50: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44  processing, or D
ec60: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
ec70: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
ec80: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
ec90: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
eca0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
ecb0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20  akes them is.** 
ecc0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
ecd0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
ece0: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74  ndle is passed t
ecf0: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
ed00: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
ed10: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
ed20: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
ed30: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
ed40: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
ed50: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
ed60: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
ed70: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
ed80: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
ed90: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
eda0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
edb0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
edc0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
edd0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
ede0: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
edf0: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
ee00: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
ee10: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
ee20: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
ee30: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
ee40: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
ee50: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
ee60: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
ee70: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
ee80: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
ee90: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
eea0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
eeb0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
eec0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
eed0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
eee0: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
eef0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
ef00: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
ef10: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
ef20: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
ef30: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
ef40: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
ef50: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
ef60: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
ef70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
ef80: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
ef90: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
efa0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
efb0: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
efc0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
efd0: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
efe0: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
eff0: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
f000: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f010: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
f020: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
f030: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
f040: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
f050: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f060: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
f070: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
f080: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
f090: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
f0a0: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72  onnection was cr
f0b0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eated..**.** {F1
f0c0: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
f0d0: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
f0e0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
f0f0: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
f100: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
f110: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
f120: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
f130: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
f140: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
f150: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f160: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  )]..**.** LIMITA
f170: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
f180: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
f190: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
f1a0: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
f1b0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
f1c0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
f1d0: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
f1e0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
f1f0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
f200: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
f210: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
f220: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
f230: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
f240: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
f250: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
f260: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
f270: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f280: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
f290: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
f2a0: 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12270}.**.** 
f2b0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
f2c0: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
f2d0: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
f2e0: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
f2f0: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
f300: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
f310: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
f320: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
f330: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
f340: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
f350: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
f360: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
f370: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
f380: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
f390: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
f3a0: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
f3b0: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
f3c0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
f3d0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
f3e0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
f3f0: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
f400: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
f410: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
f420: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
f430: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
f440: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
f450: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
f460: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
f470: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
f480: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f490: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
f4a0: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
f4b0: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
f4c0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
f4d0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
f4e0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
f4f0: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
f500: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
f510: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
f520: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
f530: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
f540: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
f550: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
f560: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
f570: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
f580: 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
f590: 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
f5a0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
f5b0: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
f5c0: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
f5d0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
f5e0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
f5f0: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
f600: 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
f610: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
f620: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
f630: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
f640: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
f650: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
f660: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
f670: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
f680: 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
f690: 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
f6a0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
f6b0: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
f6c0: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
f6d0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
f6e0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
f6f0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
f700: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
f710: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
f720: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54  **.** {F12271} T
f730: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
f740: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
f750: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
f760: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
f770: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
f780: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
f790: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
f7a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f7b0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
f7c0: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
f7d0: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
f7e0: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
f7f0: 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
f800: 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {F12272} Any SQ
f810: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
f820: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
f830: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
f840: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
f850: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
f860: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
f870: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  PT]..**.** LIMIT
f880: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  ATIONS:.**.** {A
f890: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
f8a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f8b0: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
f8c0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f8d0: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
f8e0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
f8f0: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
f900: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
f910: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
f920: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
f930: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
f940: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
f950: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
f960: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
f970: 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10510}.**.** T
f980: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
f990: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
f9a0: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
f9b0: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
f9c0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
f9d0: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
f9e0: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
f9f0: 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
fa00: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
fa10: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
fa20: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
fa30: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
fa40: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
fa50: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
fa60: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
fa70: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
fa80: 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
fa90: 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
faa0: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
fab0: 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
fac0: 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
fad0: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
fae0: 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
faf0: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
fb00: 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
fb10: 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
fb20: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
fb30: 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
fb40: 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
fb50: 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
fb60: 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
fb70: 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
fb80: 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
fb90: 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
fba0: 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
fbb0: 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
fbc0: 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
fbd0: 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
fbe0: 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
fbf0: 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
fc00: 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
fc10: 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
fc20: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
fc30: 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
fc40: 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
fc50: 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
fc60: 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
fc70: 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
fc80: 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
fc90: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
fca0: 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54  **.** {F10511} T
fcb0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  he sqlite3_compl
fcc0: 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ete() and sqlite
fcd0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 66  3_complete16() f
fce0: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20  unctions.**     
fcf0: 20 20 20 20 20 72 65 74 75 72 6e 20 74 72 75 65       return true
fd00: 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61   (non-zero) if a
fd10: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c  nd only if the l
fd20: 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61  ast non-whitespa
fd30: 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
fd40: 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e  oken in their in
fd50: 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  put is a semicol
fd60: 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69  on that is not i
fd70: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20  n between.**    
fd80: 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e 20        the BEGIN 
fd90: 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45  and END of a CRE
fda0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
fdb0: 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  ement..**.** LIM
fdc0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
fdd0: 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70  {A10512} The inp
fde0: 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ut to sqlite3_co
fdf0: 6d 70 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65  mplete() must be
fe00: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
fe10: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
fe20: 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
fe30: 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54 68 65 20  ** {A10513} The 
fe40: 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33  input to sqlite3
fe50: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75  _complete16() mu
fe60: 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
fe70: 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
fe80: 20 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e      UTF-16 strin
fe90: 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
fea0: 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
feb0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
fec0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
fed0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
fee0: 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
fef0: 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
ff00: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
ff10: 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
ff20: 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
ff30: 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31  _BUSY Errors {F1
ff40: 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2310}.**.** This
ff50: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
ff60: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
ff70: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
ff80: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
ff90: 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
ffa0: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
ffb0: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
ffc0: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
ffd0: 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
ffe0: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
fff0: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
10000 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
10010 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
10020 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
10030 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
10040 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
10050 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
10060 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
10070 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73  lock. If the bus
10080 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
10090 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
100a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c  the callback wil
100b0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  l be invoked wit
100c0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
100d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
100e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
100f0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
10100 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
10110 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
10120 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
10130 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10140 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
10150 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
10160 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
10170 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
10180 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
10190 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
101a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
101b0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
101c0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
101d0 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74  ing event.  If t
101e0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
101f0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
10200 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
10210 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
10220 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
10230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
10240 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
10250 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
10260 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
10270 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  urned..** If the
10280 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
10290 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
102a0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
102b0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
102c0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
102d0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
102e0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
102f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
10300 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
10310 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
10320 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
10330 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
10340 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
10350 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
10360 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20  tion. If SQLite 
10370 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
10380 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
10390 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
103a0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
103b0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
103c0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
103d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
103e0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
103f0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
10400 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
10410 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
10420 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
10430 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
10440 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
10450 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
10460 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
10470 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
10480 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
10490 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
104a0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
104b0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
104c0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
104d0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
104e0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
104f0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
10500 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
10510 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
10520 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
10530 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
10540 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
10550 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
10560 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
10570 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
10580 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
10590 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
105a0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
105b0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
105c0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
105d0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
105e0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
105f0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
10600 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
10610 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
10620 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
10630 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
10640 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
10650 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
10660 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
10670 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
10680 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
10690 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
106a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
106b0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
106c0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
106d0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
106e0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
106f0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
10700 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
10710 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
10720 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
10730 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
10740 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
10750 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
10760 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
10770 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
10780 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
10790 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
107a0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
107b0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
107c0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
107d0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
107e0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
107f0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
10800 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
10810 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
10820 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
10830 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
10840 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
10850 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49  t.** readers.  I
10860 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
10870 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
10880 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
10890 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
108a0 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
108b0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
108c0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
108d0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
108e0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
108f0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
10900 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
10910 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
10920 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
10930 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
10940 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f  .  This error co
10950 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
10960 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
10970 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
10980 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
10990 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
109a0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
109b0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
109c0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
109d0 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
109e0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
109f0 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
10a00 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
10a10 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
10a20 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
10a30 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
10a40 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
10a50 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
10a60 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
10a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10a80 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
10a90 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
10aa0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
10ab0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
10ac0 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68  andler.  Note th
10ad0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
10ae0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
10af0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
10b00 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
10b10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
10b20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10b30 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d  :.**.** {F12311}
10b40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
10b50 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75  sy_handler()] fu
10b60 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
10b70 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
10b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
10b90 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74  lback in the dat
10ba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10bb0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
10bc0 68 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20  he 1st.**       
10bd0 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
10be0 68 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  h a new busy han
10bf0 64 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64 20  dler identified 
10c00 62 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33  by the 2nd and 3
10c10 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rd.**          p
10c20 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
10c30 20 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64 65   {F12312} The de
10c40 66 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c  fault busy handl
10c50 65 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62  er for new datab
10c60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
10c70 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
10c80 46 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f  F12314} When two
10c90 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73   or more databas
10ca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61  e connection sha
10cb0 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  re a.**         
10cc0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
10cd0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
10ce0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
10cf0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
10d00 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10d10 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
10d20 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
10d30 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
10d40 20 20 20 20 74 68 65 20 63 61 63 68 65 20 69 73      the cache is
10d50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
10d60 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
10d70 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
10d80 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 62   {F12316} If a b
10d90 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
10da0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
10db0 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
10dc0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
10dd0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72           that pr
10de0 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
10df0 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65  ng event will re
10e00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
10e10 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  Y]..**.** {F1231
10e20 38 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  8} SQLite will i
10e30 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20  nvokes the busy 
10e40 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f  handler with two
10e50 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68   arguments which
10e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
10e70 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
10e80 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
10e90 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
10ea0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
10eb0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
10ec0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
10ed0 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
10ee0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
10ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
10f00 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
10f10 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10f20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
10f30 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49   event..**.** LI
10f40 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
10f50 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73 79   {A12319} A busy
10f60 20 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20   handler should 
10f70 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
10f80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10f90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
10fa0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
10fb0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
10fc0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
10fd0 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
10fe0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
10ff0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
11000 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
11010 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
11020 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
11030 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34  y Timeout {F1234
11040 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
11050 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
11060 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11070 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
11080 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
11090 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
110a0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
110b0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
110c0 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
110d0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
110e0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
110f0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
11100 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
11110 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
11120 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
11130 74 65 64 2e 20 7b 46 31 32 33 34 33 7d 20 41 66  ted. {F12343} Af
11140 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ter "ms" millise
11150 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
11160 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
11170 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
11180 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
11190 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
111a0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
111b0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
111c0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
111d0 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68  **.** Calling th
111e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
111f0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
11200 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
11210 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
11220 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
11230 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dlers..**.** The
11240 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
11250 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
11260 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
11270 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
11280 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11290 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
112a0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
112b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
112c0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
112d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
112e0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
112f0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
11300 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
11310 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
11320 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
11330 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  red..**.** INVAR
11340 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
11350 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2341} The [sqlit
11360 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
11370 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72  )] function over
11380 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f 72 0a  rides any prior.
11390 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
113a0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
113b0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
113c0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
113d0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
113e0 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65       on the same
113f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11400 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  tion..**.** {F12
11410 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20  343} If the 2nd 
11420 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
11430 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
11440 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68  ut()] is less th
11450 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  an.**          o
11460 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c  r equal to zero,
11470 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68   then the busy h
11480 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
11490 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20  d so that.**    
114a0 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71        all subseq
114b0 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65  uent locking eve
114c0 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  nts immediately 
114d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
114e0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  USY]..**.** {F12
114f0 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20  344} If the 2nd 
11500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
11510 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
11520 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74  ut()] is a posit
11530 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
11540 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61  number N, then a
11550 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
11560 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74   set that repeat
11570 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  edly calls.**   
11580 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65         the xSlee
11590 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68  p() method in th
115a0 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  e VFS interface 
115b0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
115c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 63  .**          loc
115d0 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69  k clears or unti
115e0 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65  l the cumulative
115f0 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65 70 6f   sleep time repo
11600 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20 20 20  rted back.**    
11610 20 20 20 20 20 20 62 79 20 78 53 6c 65 65 70 28        by xSleep(
11620 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c  ) exceeds N mill
11630 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  iseconds..*/.int
11640 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
11650 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
11660 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
11670 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
11680 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
11690 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
116a0 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a  es {F12370}.**.*
116b0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
116c0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
116d0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
116e0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
116f0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
11700 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11710 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
11720 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11730 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
11740 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
11750 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
11760 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
11770 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
11780 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
11790 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
117a0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
117b0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
117c0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
117d0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
117e0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
117f0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
11800 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
11810 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
11820 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
11830 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
11840 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
11850 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
11860 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
11870 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
11880 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
11890 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
118a0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
118b0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
118c0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
118d0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
118e0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
118f0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
11900 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
11910 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
11920 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
11930 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
11940 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
11950 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
11960 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
11970 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
11980 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
11990 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
119a0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
119b0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
119c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
119d0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
119e0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
119f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
11a00 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
11a10 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
11a20 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
11a30 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
11a40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
11a50 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
11a60 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
11a70 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
11a80 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
11a90 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
11aa0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
11ab0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
11ac0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
11ad0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
11ae0 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
11af0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
11b00 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
11b10 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
11b20 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
11b30 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
11b40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11b50 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
11b60 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
11b70 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
11b80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
11b90 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
11ba0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
11bb0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
11bc0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
11bd0 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
11be0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
11bf0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
11c00 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
11c10 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
11c20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
11c30 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
11c40 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
11c50 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
11c60 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11c70 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
11c80 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
11c90 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
11ca0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
11cb0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
11cc0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
11cd0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
11ce0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
11cf0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
11d00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
11d10 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
11d20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11d30 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
11d40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11d50 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
11d60 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11d70 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
11d80 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
11d90 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
11da0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
11db0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
11dc0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
11dd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11de0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
11df0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11e00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
11e10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11e20 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
11e30 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
11e40 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
11e50 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
11e60 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
11e70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
11e80 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
11e90 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
11ea0 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
11eb0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
11ec0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
11ed0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
11ee0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
11ef0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
11f00 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
11f10 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
11f20 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
11f30 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
11f40 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
11f50 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11f60 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
11f70 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
11f80 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
11f90 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
11fa0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
11fb0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
11fc0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
11fd0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
11fe0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
11ff0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
12000 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
12010 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
12020 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
12030 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
12040 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
12050 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
12060 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
12070 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
12080 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
12090 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
120a0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
120b0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
120c0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
120d0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
120e0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
120f0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
12100 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12110 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
12120 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
12130 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
12140 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
12150 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
12160 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
12170 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
12180 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
12190 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
121a0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
121b0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
121c0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
121d0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
121e0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
121f0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
12200 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
12210 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
12220 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
12230 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
12240 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
12250 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
12260 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
12270 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74  371} If a [sqlit
12280 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
12290 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61  fails a memory a
122a0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a  llocation, then.
122b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 66  **          it f
122c0 72 65 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  rees the result 
122d0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
122e0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73  truction, aborts
122f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
12300 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73   query in proces
12310 73 2c 20 73 6b 69 70 73 20 61 6e 79 20 73 75 62  s, skips any sub
12320 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
12330 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 20 20 20   sets the.**    
12340 20 20 20 20 20 20 2a 72 65 73 75 6c 74 70 20 6f        *resultp o
12350 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f  utput pointer to
12360 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e   NULL and return
12370 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  s [SQLITE_NOMEM]
12380 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d  ..**.** {F12373}
12390 20 49 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20   If the ncolumn 
123a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
123b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
123c0 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
123d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
123e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
123f0 6c 65 28 29 5d 20 77 72 69 74 65 73 20 74 68 65  le()] writes the
12400 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
12410 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ns in the.**    
12420 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
12430 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
12440 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74  to *ncolumn if t
12450 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
12460 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
12470 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
12480 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
12490 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
124a0 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 6e 72  12374} If the nr
124b0 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ow parameter to 
124c0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
124d0 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
124e0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
124f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  en [sqlite3_get_
12500 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 73 20  table()] writes 
12510 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
12520 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ws in the.**    
12530 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
12540 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
12550 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65 20  to *nrow if the 
12560 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20  query is.**     
12570 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20       successful 
12580 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  (if the function
12590 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
125a0 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  OK)..**.** {F123
125b0 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  76} The [sqlite3
125c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 75  _get_table()] fu
125d0 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73 20  nction sets its 
125e0 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 74  *ncolumn value t
125f0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
12600 20 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75    number of colu
12610 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
12620 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
12630 72 79 20 69 6e 20 74 68 65 20 73 71 6c 0a 2a 2a  ry in the sql.**
12640 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
12650 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f 20  ter, or to zero 
12660 69 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20  if the query in 
12670 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74 79  sql has an empty
12680 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a   result set..*/.
12690 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
126a0 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
126b0 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  *,             /
126c0 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
126d0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
126e0 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a  ar *sql,      /*
126f0 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
12700 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
12710 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20 20  **pResult,      
12720 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
12730 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
12740 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20   *nrow,         
12750 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
12760 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
12770 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
12780 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20  t *ncolumn,     
12790 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
127a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
127b0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
127c0 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
127d0 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
127e0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
127f0 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
12800 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
12810 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
12820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12830 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
12840 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
12850 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a  ions {F17400}.**
12860 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12870 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
12880 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
12890 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
128a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
128b0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
128c0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
128d0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
128e0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
128f0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
12900 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
12910 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
12920 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
12930 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
12940 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
12950 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
12960 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
12970 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
12980 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
12990 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
129a0 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
129b0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
129c0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
129d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
129e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
129f0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
12a00 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
12a10 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
12a20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
12a30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12a40 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
12a50 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
12a60 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
12a70 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12a80 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
12a90 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
12aa0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
12ab0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
12ac0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
12ad0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
12ae0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
12af0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
12b00 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
12b10 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
12b20 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
12b30 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
12b40 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
12b50 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
12b60 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
12b70 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
12b80 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
12b90 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
12ba0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
12bb0 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
12bc0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
12bd0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
12be0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
12bf0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
12c00 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
12c10 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
12c20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
12c30 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
12c40 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
12c50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
12c60 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
12c70 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
12c80 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
12c90 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
12ca0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
12cb0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
12cc0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
12cd0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
12ce0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
12cf0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
12d00 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
12d10 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
12d20 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
12d30 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
12d40 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
12d50 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12d60 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
12d70 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
12d80 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
12d90 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
12da0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
12db0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
12dc0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
12dd0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
12de0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
12df0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
12e00 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
12e10 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
12e20 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
12e30 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
12e40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12e50 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
12e60 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
12e70 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
12e80 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
12e90 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
12ea0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
12eb0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
12ec0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
12ed0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
12ee0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
12ef0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
12f00 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
12f10 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
12f20 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
12f30 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
12f40 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
12f50 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
12f60 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
12f70 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
12f80 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
12f90 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
12fa0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
12fb0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
12fc0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
12fd0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
12fe0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
12ff0 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
13000 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
13010 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
13020 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
13030 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
13040 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
13050 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
13060 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
13070 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
13080 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
13090 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
130a0 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
130b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
130c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
130d0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
130e0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
130f0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13100 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
13110 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
13120 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
13130 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
13140 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
13150 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13160 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
13170 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
13180 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
13190 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
131a0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
131b0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
131c0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
131d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
131e0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
131f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13200 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
13210 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
13220 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
13230 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
13240 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
13250 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
13260 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
13270 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
13280 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
13290 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
132a0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
132b0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
132c0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
132d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
132e0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
132f0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
13300 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
13310 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
13320 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
13330 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
13340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
13360 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
13370 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
13380 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
13390 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
133a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
133b0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
133c0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
133d0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
133e0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
133f0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
13400 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
13410 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
13420 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
13430 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
13440 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
13450 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
13460 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
13470 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
13480 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
13490 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
134a0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
134b0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
134c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
134d0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
134e0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
134f0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
13500 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
13510 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
13520 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
13530 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
13540 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
13550 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
13560 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
13570 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
13580 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
13590 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
135a0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
135b0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
135c0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
135d0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
135e0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
135f0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
13600 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
13610 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13620 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
13630 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
13640 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
13650 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
13660 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
13670 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
13680 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
13690 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
136a0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
136b0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
136c0 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
136d0 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
136e0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
136f0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
13700 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
13710 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
13720 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
13730 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
13740 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
13750 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
13760 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ng. {END}.**.** 
13770 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
13780 2a 20 7b 46 31 37 34 30 33 7d 20 20 54 68 65 20  * {F17403}  The 
13790 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
137a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
137b0 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _vmprintf()] int
137c0 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20  erfaces.**      
137d0 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68       return eith
137e0 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  er pointers to z
137f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
13800 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c  TF-8 strings hel
13810 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d in.**         
13820 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65    memory obtaine
13830 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13840 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c  malloc()] or NUL
13850 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a  L pointers if.**
13860 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c             a cal
13870 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  l to [sqlite3_ma
13880 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a  lloc()] fails..*
13890 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20 20 54  *.** {F17406}  T
138a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
138b0 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
138c0 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d  e writes a zero-
138d0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
138e0 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
138f0 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75  ring into the bu
13900 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  ffer pointed to 
13910 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
13920 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
13930 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68       provided th
13940 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72  at the first par
13950 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65  ameter is greate
13960 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a  r than zero..**.
13970 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20 54 68 65  ** {F17407}  The
13980 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
13990 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
139a0 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73  does not write s
139b0 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  lots of.**      
139c0 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20       its output 
139d0 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f  buffer (the seco
139e0 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75  nd parameter) ou
139f0 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a  tside the range.
13a00 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
13a10 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77  0 through N-1 (w
13a20 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69  here N is the fi
13a30 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  rst parameter).*
13a40 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61  *           rega
13a50 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65  rdless of the le
13a60 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
13a70 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
13a80 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65  requested by the
13a90 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63   format specific
13aa0 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a  ation..*/.char *
13ab0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
13ac0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
13ad0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
13ae0 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
13af0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
13b00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
13b10 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
13b20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
13b30 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
13b40 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
13b50 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
13b60 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17300}.**.** 
13b70 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
13b80 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
13b90 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
13ba0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
13bb0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
13bc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
13bd0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
13be0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
13bf0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
13c00 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
13c10 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
13c20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
13c30 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
13c40 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
13c50 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
13c60 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
13c70 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
13c80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
13c90 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
13ca0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
13cb0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
13cc0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
13cd0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
13ce0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
13cf0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
13d00 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
13d10 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
13d20 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
13d30 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
13d40 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
13d50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
13d60 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  .  If the parame
13d70 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
13d80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
13d90 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
13da0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
13db0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
13dc0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
13dd0 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
13de0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
13df0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
13e00 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
13e10 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
13e20 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
13e30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
13e40 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
13e50 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
13e60 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
13e70 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  .  The sqlite3_f
13e80 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
13e90 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
13ea0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
13eb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
13ec0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
13ed0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
13ee0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
13ef0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
13f00 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
13f10 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
13f20 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
13f30 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
13f40 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
13f50 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
13f60 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
13f70 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
13f80 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
13f90 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
13fa0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
13fb0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
13fc0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
13fd0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
13fe0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
13ff0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
14000 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
14010 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
14020 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
14030 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
14040 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
14050 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66  c() or sqlite3_f
14060 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ree()..**.** The
14070 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14080 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
14090 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
140a0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
140b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
140c0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
140d0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
140e0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
140f0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
14100 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14110 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
14120 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
14130 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
14140 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14150 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
14160 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
14170 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
14180 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
14190 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
141a0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
141b0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
141c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
141d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
141e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
141f0 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
14200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14210 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14220 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
14230 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
14240 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
14250 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
14260 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
14270 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
14280 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
14290 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
142a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
142b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
142c0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
142d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
142e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
142f0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
14300 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
14310 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
14320 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
14330 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
14340 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
14350 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
14360 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
14370 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
14380 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
14390 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
143a0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
143b0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
143c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
143d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
143e0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
143f0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
14400 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
14410 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
14420 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
14430 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
14440 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
14450 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
14460 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
14470 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14480 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
14490 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
144a0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
144b0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
144c0 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
144d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
144e0 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
144f0 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  on of the memory
14500 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
14510 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68  ystem uses.** th
14520 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
14530 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
14540 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
14550 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
14560 61 72 79 2e 0a 2a 2a 20 7b 46 31 37 33 38 32 7d  ary..** {F17382}
14570 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
14580 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14590 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
145a0 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
145b0 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70  i>NNN</i> C prep
145c0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28  rocessor macro (
145d0 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
145e0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
145f0 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  r), then SQLite 
14600 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20  create a static 
14610 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
14620 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  t.** <i>NNN</i> 
14630 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
14640 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61  d uses that arra
14650 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  y for all of its
14660 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f   dynamic.** memo
14670 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14680 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
14690 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  tional memory al
146a0 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a  locator options.
146b0 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ** may be added 
146c0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
146d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
146e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
146f0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
14700 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
14710 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
14720 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
14730 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
14740 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
14750 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
14760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
14770 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
14780 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
14790 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
147a0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
147b0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
147c0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
147d0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
147e0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
147f0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
14800 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
14810 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
14820 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
14830 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
14840 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
14850 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
14860 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
14870 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
14880 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
14890 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
148a0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
148b0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
148c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
148d0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
148e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
148f0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
14900 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
14910 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
14920 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
14930 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
14940 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
14950 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
14960 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
14970 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
14980 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7303}  The [sqli
14990 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
149a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
149b0 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
149c0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
149d0 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65    a newly checke
149e0 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61  d-out block of a
149f0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
14a00 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  of memory.**    
14a10 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
14a20 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
14a30 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  r it returns NUL
14a40 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c  L if it is unabl
14a50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
14a60 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65  o fulfill the re
14a70 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  quest..**.** {F1
14a80 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69  7304}  The [sqli
14a90 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
14aa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
14ab0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
14ac0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
14ad0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
14ae0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e  r equal to zero.
14af0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20  .**.** {F17305} 
14b00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   The [sqlite3_fr
14b10 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ee(P)] interface
14b20 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79   releases memory
14b30 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
14b40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
14b50 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
14b60 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
14b70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14b80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ,.**           m
14b90 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62  aking it availab
14ba0 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a  le for reuse..**
14bb0 0a 2a 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20  .** {F17306}  A 
14bc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
14bd0 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20  _free(NULL)] is 
14be0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
14bf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d  ..**.** {F17310}
14c00 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
14c10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
14c20 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
14c30 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
14c40 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
14c50 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a  te3_malloc(N)]..
14c60 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20  **.** {F17312}  
14c70 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
14c80 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d  e3_realloc(P,0)]
14c90 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
14ca0 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
14cb0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
14cc0 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a  3_free(P)]..**.*
14cd0 2a 20 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20  * {F17315}  The 
14ce0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
14cf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14d00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  ()], [sqlite3_re
14d10 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
14d20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69         and [sqli
14d30 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
14d40 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72  all of its memor
14d50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64  y allocation and
14d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65  .**           de
14d70 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14d80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d  ..**.** {F17318}
14d90 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72    The [sqlite3_r
14da0 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74  ealloc(P,N)] int
14db0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
14dc0 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a  ither a pointer.
14dd0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
14de0 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b  a block of check
14df0 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66  ed-out memory of
14e00 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
14e10 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
14e20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
14e30 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
14e40 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
14e50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d  ..**.** {F17321}
14e60 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
14e70 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
14e80 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
14e90 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
14ea0 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
14eb0 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74  copies the first
14ec0 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74   K bytes of cont
14ed0 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20  ent from P into 
14ee0 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20  the newly.**    
14ef0 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64         allocated
14f00 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20   block, where K 
14f10 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  is the lesser of
14f20 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20   N and the size 
14f30 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
14f40 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
14f50 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20 57 68  .** {F17322}  Wh
14f60 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
14f70 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
14f80 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
14f90 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
14fa0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
14fb0 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
14fc0 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 33  P..**.** {F17323
14fd0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
14fe0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
14ff0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
15000 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
15010 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
15020 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
15030 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
15040 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
15050 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
15060 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
15070 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15080 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
15090 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
150a0 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
150b0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
150c0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
150d0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
150e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e  .**           in
150f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
15100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
15110 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
15120 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
15130 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
15140 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
15150 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35  ed..**.** {A1735
15160 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
15170 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
15180 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
15190 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  art of.**       
151a0 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d      a block of m
151b0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
151c0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
151d0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
151e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65      [sqlite3_fre
151f0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
15200 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
15210 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
15220 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
15230 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
15240 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
15250 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
15260 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
15270 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
15280 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
15290 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a  tics {F17370}.**
152a0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
152b0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
152c0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
152d0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
152e0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
152f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15300 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
15310 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
15320 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
15330 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
15340 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
15350 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
15360 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
15370 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
15380 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20  .**.** {F17371} 
15390 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
153a0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
153b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
153c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
153d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d  **          of m
153e0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
153f0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
15400 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
15410 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  eed)..**.** {F17
15420 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  373} The [sqlite
15430 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15440 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
15450 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
15460 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  m.**          va
15470 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
15480 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
15490 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
154a0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
154b0 20 20 20 20 20 77 61 73 20 6c 61 73 74 20 72 65       was last re
154c0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  set..**.** {F173
154d0 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72  74} The values r
154e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
154f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15500 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
15510 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
15520 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15530 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
15540 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  head.**         
15550 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
15560 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
15570 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
15580 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
15590 20 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f            but no
155a0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
155b0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
155c0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
155d0 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  brary.**        
155e0 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20    routines that 
155f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15600 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
15610 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20  ** {F17375} The 
15620 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
15630 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
15640 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
15650 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  alue of.**      
15660 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
15670 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
15680 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
15690 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
156a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
156b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
156c0 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54  r()] is true.  T
156d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
156e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
156f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15700 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
15710 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
15720 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20   mark.**        
15730 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72    prior to the r
15740 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
15750 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
15760 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
15770 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
15780 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
15790 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
157a0 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
157b0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
157c0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
157d0 65 6e 65 72 61 74 6f 72 20 7b 46 31 37 33 39 30  enerator {F17390
157e0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  }.**.** SQLite c
157f0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
15800 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
15810 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
15820 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
15830 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
15840 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65  andom ROWIDs whe
15850 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
15860 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
15870 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
15880 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
15890 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52  rgest possible R
158a0 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20  OWID.  The PRNG 
158b0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
158c0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
158d0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
158e0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
158f0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
15900 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
15910 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
15920 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
15930 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
15940 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
15950 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
15960 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
15970 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
15980 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
15990 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
159a0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
159b0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
159c0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
159d0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
159e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
159f0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
15a00 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
15a10 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
15a20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
15a30 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
15a40 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
15a50 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
15a60 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
15a70 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
15a80 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
15a90 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
15aa0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
15ab0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
15ac0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
15ad0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
15ae0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
15af0 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
15b00 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
15b10 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
15b20 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
15b30 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
15b40 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
15b50 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
15b60 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
15b70 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
15b80 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
15b90 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
15ba0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
15bb0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
15bc0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
15bd0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
15be0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
15bf0 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500}.**.** This 
15c00 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
15c10 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
15c20 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
15c30 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
15c40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15c50 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
15c60 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
15c70 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
15c80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
15c90 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
15ca0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
15cb0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
15cc0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
15cd0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
15ce0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
15cf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
15d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
15d10 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
15d20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
15d30 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
15d40 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
15d50 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
15d60 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
15d70 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
15d80 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
15d90 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
15da0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
15db0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
15dc0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
15dd0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
15de0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
15df0 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
15e00 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
15e10 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
15e20 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
15e30 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
15e40 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
15e50 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
15e60 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
15e70 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
15e80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
15e90 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
15ea0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
15eb0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
15ec0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
15ed0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
15ee0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
15ef0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
15f00 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
15f10 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
15f20 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
15f30 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
15f40 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
15f50 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
15f60 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
15f70 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
15f80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15f90 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
15fa0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
15fb0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
15fc0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
15fd0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
15fe0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
15ff0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16000 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
16010 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
16020 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
16030 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
16040 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
16050 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
16060 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
16070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16080 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16090 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
160a0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
160b0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
160c0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
160d0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
160e0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
160f0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
16100 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16110 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
16120 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
16130 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16140 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
16150 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
16160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
16170 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
16180 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
16190 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
161a0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
161b0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
161c0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
161d0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
161e0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
161f0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
16200 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
16210 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
16220 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
16230 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
16240 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
16250 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
16260 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
16270 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
16280 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16290 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
162a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
162b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
162c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
162d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
162e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
162f0 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
16300 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
16310 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
16320 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
16330 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
16340 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
16350 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
16360 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
16370 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
16380 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
16390 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
163a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
163b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
163c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
163d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
163e0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
163f0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
16400 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
16410 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
16420 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
16430 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
16440 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16450 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
16460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16470 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
16480 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
16490 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
164a0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
164b0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
164c0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
164d0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
164e0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
164f0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
16500 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
16510 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
16520 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
16530 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
16540 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
16550 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
16560 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
16570 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
16580 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
16590 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
165a0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
165b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
165c0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
165d0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
165e0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
165f0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
16600 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
16610 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
16620 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
16630 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
16640 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
16650 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
16660 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
16670 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
16680 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
16690 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
166a0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
166b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
166c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
166d0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
166e0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
166f0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
16700 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
16710 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
16720 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
16730 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
16740 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
16750 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
16760 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
16770 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
16780 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
16790 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
167a0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
167b0 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
167c0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
167d0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
167e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
167f0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
16800 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
16810 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
16820 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
16830 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
16840 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62  ous call.  Disab
16850 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
16860 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
16870 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
16880 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
16890 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
168a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
168b0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61   Note that the a
168c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
168d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
168e0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
168f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
16900 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
16910 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
16920 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
16930 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
16940 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
16950 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
16960 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  p()]..**.** INVA
16970 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
16980 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12501} The [sqli
16990 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
169a0 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  er(D,...)] inter
169b0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
169c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
169d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
169e0 20 77 69 74 68 20 64 61 74 61 62 61 73 65 20 63   with database c
169f0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a  onnection D..**.
16a00 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20  ** {F12502} The 
16a10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16a20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
16a30 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
16a40 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
16a50 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e   being compiled.
16a60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20  .**.** {F12503} 
16a70 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
16a80 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
16a90 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ns any value oth
16aa0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
16ab0 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f      [SQLITE_IGNO
16ac0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
16ad0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16ae0 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  Y], then.**     
16af0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
16b00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16b10 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16b20 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ll that caused.*
16b30 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
16b40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16b50 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
16b60 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20  fail with an.** 
16b70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16b80 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
16b90 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  de and an approp
16ba0 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
16bb0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  age..**.** {F125
16bc0 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  04} When the aut
16bd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16be0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16bf0 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74  _OK], the operat
16c00 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
16c10 64 65 73 63 72 69 62 65 64 20 69 73 20 70 72 6f  described is pro
16c20 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e  cessed normally.
16c30 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20  .**.** {F12505} 
16c40 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
16c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
16c60 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
16c70 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  Y], the.**      
16c80 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
16c90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
16ca0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
16cb0 61 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a  at caused the.**
16cc0 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
16cd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
16ce0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a   run shall fail.
16cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
16d00 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   an [SQLITE_ERRO
16d10 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
16d20 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
16d30 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  ge.**          e
16d40 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61  xplaining that a
16d50 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
16d60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20  .**.** {F12506} 
16d70 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
16d80 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20  r code (the 2nd 
16d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16da0 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20   authorizer.**  
16db0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
16dc0 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  ) is [SQLITE_REA
16dd0 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f  D] and the autho
16de0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16df0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
16e00 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52     [SQLITE_IGNOR
16e10 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 72 65  E], then the pre
16e20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
16e30 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
16e40 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  o.**          in
16e50 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75  sert a NULL valu
16e60 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
16e70 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
16e80 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
16e90 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20  *          been 
16ea0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
16eb0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
16ec0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  urned..**.** {F1
16ed0 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75 74  2507} If the aut
16ee0 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
16ef0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
16f00 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
16f10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
16f20 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68  llback) is anyth
16f30 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
16f40 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68  SQLITE_READ], th
16f50 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  en.**          a
16f60 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49   return of [SQLI
16f70 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74  TE_IGNORE] has t
16f80 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61  he same effect a
16f90 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e  s [SQLITE_DENY].
16fa0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20  .**.** {F12510} 
16fb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
16fc0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
16fd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16fe0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20  s a copy of.**  
16ff0 20 20 20 20 20 20 20 20 74 68 65 20 74 68 69 72          the thir
17000 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
17010 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17020 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
17030 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
17040 46 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f  F12511} The seco
17050 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17060 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
17070 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
17080 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
17090 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
170a0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
170b0 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  s the particular
170c0 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20   action.**      
170d0 20 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72      to be author
170e0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
170f0 35 31 32 7d 20 54 68 65 20 74 68 69 72 64 20 74  512} The third t
17100 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
17110 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
17120 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20  allback are.**  
17130 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
17140 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
17150 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20  that contain.** 
17160 20 20 20 20 20 20 20 20 20 61 64 64 69 74 69 6f           additio
17170 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75  nal details abou
17180 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
17190 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
171a0 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61  *.** {F12520} Ea
171b0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
171c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
171d0 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a  er()] overrides.
171e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 79 20  **          any 
171f0 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61  previously insta
17200 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e  lled authorizer.
17210 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20  .**.** {F12521} 
17220 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65  A NULL authorize
17230 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  r means that no 
17240 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
17250 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
17260 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ck is invoked..*
17270 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68  *.** {F12522} Th
17280 65 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72  e default author
17290 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f  izer is NULL..*/
172a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
172b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
172c0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
172d0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
172e0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
172f0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
17300 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
17310 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
17320 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
17330 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
17340 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
17350 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a  s {F12590}.**.**
17360 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17370 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
17380 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17390 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
173a0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
173b0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
173c0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
173d0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
173e0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
173f0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
17400 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
17410 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
17420 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
17430 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17440 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17450 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
17460 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
17470 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
17480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17490 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
174a0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
174b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
174c0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
174d0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
174e0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
174f0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
17500 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
17510 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
17520 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
17530 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
17540 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a  es {F12550}.**.*
17550 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
17560 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
17570 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
17580 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
17590 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
175a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
175b0 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
175c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
175d0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
175e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
175f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
17600 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
17610 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
17620 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
17630 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
17640 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
17650 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
17660 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
17670 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
17680 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
17690 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
176a0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
176b0 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
176c0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
176d0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
176e0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
176f0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
17700 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
17710 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
17720 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
17730 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
17740 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
17750 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
17760 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
17770 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
17780 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
17790 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20  meter.  The 5th 
177a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
177b0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
177c0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
177d0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
177e0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
177f0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
17800 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68   applicable.  Th
17810 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
17820 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
17830 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
17840 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17850 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
17860 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
17870 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
17880 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
17890 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
178a0 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
178b0 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
178c0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
178d0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
178e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
178f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31  S:.**.** {F12551
17900 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
17910 61 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ameter to an.** 
17920 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
17930 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17940 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
17950 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79  llback] is alway
17960 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
17970 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
17980 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
17990 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  er code] that sp
179a0 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63 74  ecifies what act
179b0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
179c0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
179d0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  zed..**.** {F125
179e0 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20  52} The 3rd and 
179f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
17a00 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
17a10 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
17a20 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17a30 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61  orization callba
17a40 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ck].**          
17a50 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
17a60 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
17a70 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a  ding on which.**
17a80 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
17a90 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69  E_COPY | authori
17aa0 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65  zer code] is use
17ab0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17ac0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
17ad0 20 7b 46 31 32 35 35 33 7d 20 54 68 65 20 35 74   {F12553} The 5t
17ae0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
17af0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
17b00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17b10 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
17b20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73  zer callback] is
17b30 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
17b40 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74        of the dat
17b50 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20  abase (example: 
17b60 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
17b70 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
17b80 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ble..**.** {F125
17b90 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61  54} The 6th para
17ba0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
17bb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
17bc0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17bd0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
17be0 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e  llback] is the n
17bf0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
17c00 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
17c10 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
17c20 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
17c30 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20  sible for.**    
17c40 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73        the access
17c50 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
17c60 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
17c70 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
17c80 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  tly from.**     
17c90 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53       top-level S
17ca0 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
17cb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17cc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17cd0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
17ce0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
17cf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
17d00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17d10 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
17d20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
17d30 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
17d40 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17d50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
17d60 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
17d70 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17d80 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17d90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17da0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
17db0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
17dc0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
17dd0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
17de0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17df0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
17e00 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
17e10 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17e20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17e30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17e40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
17e50 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
17e60 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
17e70 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17e80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17e90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
17ea0 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
17eb0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
17ec0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17ed0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17ee0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
17ef0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
17f00 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
17f10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f30 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
17f40 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
17f50 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
17f60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17f80 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
17f90 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
17fa0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
17fb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17fc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17fd0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
17fe0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
17ff0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18000 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18020 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
18030 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
18040 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18050 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18060 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18070 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
18080 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
18090 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
180a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
180b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
180c0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
180d0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
180e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
180f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18110 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
18120 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
18130 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18140 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18150 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18160 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18170 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
18180 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18190 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
181a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
181b0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
181c0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
181d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
181e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
181f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
18200 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
18210 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
18220 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18230 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18240 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
18250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
18260 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18270 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18280 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18290 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
182a0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
182b0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
182c0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
182d0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
182e0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
182f0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
18300 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18310 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
18320 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18330 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
18340 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
18350 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
18360 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18370 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18380 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
18390 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
183a0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
183b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
183c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
183d0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
183e0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
183f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18400 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
18410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18420 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
18430 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
18440 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
18450 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18470 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
18480 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
18490 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
184a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
184b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
184c0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
184d0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
184e0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
184f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18510 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
18520 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
18530 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
18540 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
18560 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
18570 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
18580 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18590 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
185a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
185b0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
185c0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
185d0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
185e0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
185f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18600 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
18610 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
18620 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
18630 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18640 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
18650 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
18660 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f   31   /* Functio
18670 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  n Name   NULL   
18680 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18690 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
186a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
186b0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
186c0 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
186d0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
186e0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
186f0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32   Functions {F122
18700 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  80}.**.** These 
18710 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
18720 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
18730 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
18740 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
18750 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
18760 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
18770 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18780 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ts..**.** The ca
18790 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
187a0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
187b0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
187c0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
187d0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
187e0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
187f0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
18800 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
18810 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ()]..** The call
18820 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55  back returns a U
18830 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
18840 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
18850 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74  ent text.** as t
18860 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
18870 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
18880 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
18890 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72   callbacks occur
188a0 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
188b0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
188c0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
188d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
188e0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
188f0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
18900 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
18910 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
18920 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ger..**.** The c
18930 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18940 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
18950 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
18960 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
18970 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
18980 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
18990 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
189a0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
189b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
189c0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
189d0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
189e0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
189f0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
18a00 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
18a10 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
18a20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f   The sqlite3_pro
18a30 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75  file() API is cu
18a40 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
18a50 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
18a60 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63  and.** is subjec
18a70 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
18a80 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75  emoval in a futu
18a90 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a  re release..**.*
18aa0 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65  * The trigger re
18ab0 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20  porting feature 
18ac0 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  of the trace cal
18ad0 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65  lback is conside
18ae0 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  red.** experimen
18af0 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
18b00 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
18b10 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
18b20 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46  e releases..** F
18b30 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
18b40 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  f SQLite might a
18b50 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63  lso add new trac
18b60 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e  e callback.** in
18b70 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  vocations..**.**
18b80 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
18b90 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20  ** {F12281} The 
18ba0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18bb0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
18bc0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
18bd0 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
18be0 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c   whenever an SQL
18bf0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
18c00 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75   begins to execu
18c10 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  te and.**       
18c20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 72     whenever a tr
18c30 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
18c40 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
18c50 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32   run..**.** {F12
18c60 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  282} Each call t
18c70 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
18c80 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  ()] overrides th
18c90 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  e previously.** 
18ca0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
18cb0 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61  red trace callba
18cc0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  ck..**.** {F1228
18cd0 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20  3} A NULL trace 
18ce0 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65  callback disable
18cf0 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s tracing..**.**
18d00 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20 66 69   {F12284} The fi
18d10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
18d20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
18d30 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
18d40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
18d50 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
18d60 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  s the 3rd argume
18d70 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
18d80 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  race()]..**.** {
18d90 46 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f  F12285} The seco
18da0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
18db0 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
18dc0 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  k is a.**       
18dd0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
18de0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
18df0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f  containing the o
18e00 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20  riginal text.** 
18e10 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
18e20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
18e30 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69   it was passed i
18e40 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nto [sqlite3_pre
18e50 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20  pare_v2()].**   
18e60 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71         or the eq
18e70 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20  uivalent, or an 
18e80 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69  SQL comment indi
18e90 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e  cating the begin
18ea0 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
18eb0 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75   of a trigger su
18ec0 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20  bprogram..**.** 
18ed0 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c  {F12287} The cal
18ee0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18ef0 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
18f00 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
18f10 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
18f20 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20          as each 
18f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
18f40 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nishes..**.** {F
18f50 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74  12288} The first
18f60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18f70 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
18f80 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
18f90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
18fa0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
18fb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
18fc0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
18fd0 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  289} The second 
18fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18ff0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
19000 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  k is a.**       
19010 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
19020 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
19030 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
19040 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20  e complete text 
19050 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
19060 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19070 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65   as it was proce
19080 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ssed by [sqlite3
19090 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
190a0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
190b0 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a  e equivalent..**
190c0 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65  .** {F12290} The
190d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
190e0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
190f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65  callback is an e
19100 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20  stimate.**      
19110 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65      of the numbe
19120 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  r of nanoseconds
19130 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
19140 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a  ime required to.
19150 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 20  **          run 
19160 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19170 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20  t from start to 
19180 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20  finish..*/.void 
19190 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
191a0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
191b0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
191c0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
191d0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
191e0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
191f0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
19200 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
19210 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
19220 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
19230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19240 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
19250 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
19260 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10}.**.** This r
19270 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
19280 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
19290 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70  ction - the.** p
192a0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
192b0 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b   - that is invok
192c0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
192d0 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72  during long.** r
192e0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  unning calls to 
192f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
19300 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
19310 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
19320 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e  e3_get_table()].
19330 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
19340 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
19350 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
19360 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
19370 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
19380 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uery..**.** If t
19390 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
193a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
193b0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
193c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
193d0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
193e0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
193f0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
19400 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
19410 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61  ton on a GUI dia
19420 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49  log box..**.** I
19430 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
19440 20 7b 46 31 32 39 31 31 7d 20 54 68 65 20 63 61   {F12911} The ca
19450 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19460 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19470 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19480 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20  andler().**     
19490 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
194a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
194b0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
194c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20   calls to.**    
194d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
194e0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tep()]..**.** {F
194f0 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72  12912} The progr
19500 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
19510 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
19520 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c   every N virtual
19530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63  .**          mac
19540 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68  hine opcodes, wh
19550 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
19560 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19570 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19580 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
19590 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c  s_handler()] cal
195a0 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65  l that registere
195b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
195c0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20  e callback.  If 
195d0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  N is less than 1
195e0 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  , sqlite3_progre
195f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
19600 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73           acts as
19610 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72   if a NULL progr
19620 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20  ess handler had 
19630 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a  been specified..
19640 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54  **.** {F12913} T
19650 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19660 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69  back itself is i
19670 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
19680 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20   third.**       
19690 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73     argument to s
196a0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
196b0 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a  handler()..**.**
196c0 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f   {F12914} The fo
196d0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
196e0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
196f0 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61  s_handler() is a
19700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69  .**          voi
19710 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
19720 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
19730 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
19740 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65        function e
19750 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
19760 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
19770 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c  12915} If a call
19780 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
19790 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20  p()] results in 
197a0 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63  fewer than N opc
197b0 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  odes.**         
197c0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
197d0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
197e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ss callback is n
197f0 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  ever invoked..**
19800 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65  .** {F12916} Eve
19810 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ry call to [sqli
19820 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19830 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
19840 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61      overwrites a
19850 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ny previously re
19860 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73  gistered progres
19870 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  s handler..**.**
19880 20 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65   {F12917} If the
19890 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
198a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  r callback is NU
198b0 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72  LL then no progr
198c0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
198d0 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
198e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  ed..**.** {F1291
198f0 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  8} If the progre
19900 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
19910 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
19920 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a  er than 0, then.
19930 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19940 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66  behavior is a if
19950 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
19960 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20  upt()] had been 
19970 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  called..*/.void 
19980 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19990 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
199a0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
199b0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
199c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
199d0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
199e0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
199f0 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a  n {F12700}.**.**
19a00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19a10 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
19a20 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f  atabase file who
19a30 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e  se name is given
19a40 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   by the.** filen
19a50 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68  ame argument. Th
19a60 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
19a70 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
19a80 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
19a90 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
19aa0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
19ab0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
19ac0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
19ad0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
19ae0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
19af0 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62  en16(). A [datab
19b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19b10 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
19b20 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
19b30 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
19b40 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
19b50 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
19b60 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
19b70 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
19b80 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
19b90 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
19ba0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
19bb0 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
19bc0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
19bd0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
19be0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
19bf0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
19c00 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68  ** object. If th
19c10 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
19c20 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
19c30 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
19c40 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
19c50 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
19c60 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
19c70 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
19c80 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
19c90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
19ca0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
19cb0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
19cc0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
19cd0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
19ce0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
19cf0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
19d00 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a  n of the error..
19d10 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
19d20 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
19d30 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
19d40 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
19d50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
19d60 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
19d70 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
19d80 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
19d90 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
19da0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
19db0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
19dc0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
19dd0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
19de0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
19df0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
19e00 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
19e10 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
19e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19e30 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
19e40 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
19e50 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
19e60 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
19e70 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
19e80 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
19e90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19ea0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
19eb0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
19ec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
19ed0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
19ee0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
19ef0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
19f00 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
19f10 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
19f20 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
19f30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
19f40 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   The flags param
19f50 65 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20  eter can be one 
19f60 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  of:.**.** <dl>.*
19f70 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
19f80 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
19f90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
19fa0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19fb0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
19fc0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
19fd0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
19fe0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
19ff0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1a000 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
1a010 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1a020 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1a030 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1a040 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1a050 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1a060 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1a070 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1a080 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1a090 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1a0a0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1a0b0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1a0c0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1a0d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1a0e0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1a0f0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1a100 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1a110 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
1a120 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1a130 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1a140 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1a150 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a160 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1a170 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1a180 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1a190 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1a1a0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1a1b0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1a1c0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1a1d0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1a1e0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1a1f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1a200 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1a210 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  6().</dd>.** </d
1a220 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1a230 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1a240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a250 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1a260 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1a270 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1a280 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1a290 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1a2a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
1a2b0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1a2c0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1a2d0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1a2e0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1a2f0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1a300 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1a310 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
1a320 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1a330 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1a340 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1a350 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1a360 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1a370 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1a380 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1a390 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1a3a0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1a3b0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1a3c0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1a3d0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1a3e0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1a3f0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1a400 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1a410 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1a420 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1a430 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1a440 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1a450 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1a460 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1a470 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1a480 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  guity..**.** If 
1a490 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1a4a0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1a4b0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1a4c0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1a4d0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1a4e0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1a4f0 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
1a500 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1a510 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1a520 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1a530 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1a540 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1a550 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
1a560 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1a570 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1a580 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1a590 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1a5a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1a5b0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1a5c0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1a5d0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1a5e0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1a5f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a600 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
1a610 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1a620 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
1a630 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1a640 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1a650 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1a660 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1a670 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
1a680 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
1a690 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
1a6a0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
1a6b0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
1a6c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1a6d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1a6e0 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
1a6f0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
1a700 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
1a710 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
1a720 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
1a730 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
1a740 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
1a750 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
1a760 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
1a770 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
1a780 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
1a790 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1a7a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a7b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ()..**.** INVARI
1a7c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
1a7d0 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  701} The [sqlite
1a7e0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1a7f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1a800 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1a810 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a820 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72  )] interfaces cr
1a830 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20  eate a new.**   
1a840 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1a850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73   connection] ass
1a860 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1a870 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74           the dat
1a880 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e  abase file given
1a890 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20   in their first 
1a8a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1a8b0 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66 69   {F12702} The fi
1a8c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1a8d0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1a8e0 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  s UTF-8.**      
1a8f0 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33      for [sqlite3
1a900 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
1a910 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1a920 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a   and as UTF-16.*
1a930 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68  *          in th
1a940 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1a950 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
1a960 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
1a970 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75 63  * {F12703} A suc
1a980 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
1a990 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f  on of [sqlite3_o
1a9a0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1a9b0 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
1a9c0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1a9d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
1a9e0 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20  rites a pointer 
1a9f0 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  to a new.**     
1aa00 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1aa10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20  onnection] into 
1aa20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  *ppDb..**.** {F1
1aa30 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  2704} The [sqlit
1aa40 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1aa50 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1aa60 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1aa70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1aa80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72  ()] interfaces r
1aa90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1aaa0 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a  ] upon success,.
1aab0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61  **          or a
1aac0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
1aad0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61  rror code] on fa
1aae0 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ilure..**.** {F1
1aaf0 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c  2706} The defaul
1ab00 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
1ab10 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
1ab20 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
1ab30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1ab40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
1ab50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1ab60 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46  2()] will be UTF
1ab70 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  -8..**.** {F1270
1ab80 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  7} The default t
1ab90 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
1aba0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
1abb0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
1abc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1abd0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c  e3_open16()] wil
1abe0 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a  l be UTF-16..**.
1abf0 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20  ** {F12709} The 
1ac00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c  [sqlite3_open(F,
1ac10 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  D)] interface is
1ac20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a   equivalent to.*
1ac30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1ac40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1ac50 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20  G,0)] where the 
1ac60 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  G parameter is.*
1ac70 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
1ac80 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1ac90 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  E]|[SQLITE_OPEN_
1aca0 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  CREATE]..**.** {
1acb0 46 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47  F12711} If the G
1acc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1acd0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1ace0 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
1acf0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1ad00 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1ad10 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1ad20 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  Y] then the data
1ad30 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a  base is opened.*
1ad40 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72  *          for r
1ad50 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a  eading only..**.
1ad60 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74  ** {F12712} If t
1ad70 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1ad80 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1ad90 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1ada0 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1adb0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1adc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1add0 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65  DWRITE] then the
1ade0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1adf0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
1ae00 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1ae10 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1ae20 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20   or for reading 
1ae30 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20  only if the.**  
1ae40 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20          file is 
1ae50 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1ae60 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1ae70 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b   system..**.** {
1ae80 46 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47  F12713} If the G
1ae90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1aea0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
1aeb0 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74  ,D,G,V)] omits t
1aec0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1aed0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1aee0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1aef0 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1af00 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1af10 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1af20 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1af30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1af40 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74 68  * {F12714} If th
1af50 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1af60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
1af70 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1af80 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1af90 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1afa0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1afb0 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1afc0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1afd0 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1afe0 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e  usly exist, then
1aff0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1b000 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e  ade to create an
1b010 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1b020 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74  itialize the dat
1b030 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  abase..**.** {F1
1b040 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c  2717} If the fil
1b050 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74  ename argument t
1b060 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1b070 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1b080 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
1b090 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
1b0a0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a  open_v2()] is ":
1b0b0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1b0c0 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20  n private,.**   
1b0d0 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c         ephemeral
1b0e0 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  , in-memory data
1b0f0 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20  base is created 
1b100 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1b110 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on..**          
1b120 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
1b130 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
1b140 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1b150 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
1b160 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
1b170 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
1b180 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  do>.**.** {F1271
1b190 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  9} If the filena
1b1a0 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  me is NULL or an
1b1b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1b1c0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a  hen a private,.*
1b1d0 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1b1e0 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74  eral on-disk dat
1b1f0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1b200 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  eated..**       
1b210 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
1b220 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
1b230 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1b240 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
1b250 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
1b260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
1b270 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
1b280 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62  2721} The [datab
1b290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b2a0 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69  created by [sqli
1b2b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1b2c0 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  G,V)].**        
1b2d0 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b    will use the [
1b2e0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b2f0 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62  ect identified b
1b300 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65  y the V paramete
1b310 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  r,.**          o
1b320 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  r the default [s
1b330 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1b340 63 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c  ct if V is a NUL
1b350 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1b360 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b 64   {F12723} Two [d
1b370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b380 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20  ons] will share 
1b390 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69  a common cache i
1b3a0 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20  f both were.**  
1b3b0 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77          opened w
1b3c0 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53  ith the same VFS
1b3d0 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63   while [shared c
1b3e0 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65  ache mode] was e
1b3f0 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20  nabled and.**   
1b400 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66         if both f
1b410 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65  ilenames compare
1b420 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d   equal using mem
1b430 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69  cmp() after havi
1b440 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20  ng been.**      
1b450 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79      processed by
1b460 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1b470 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  s | xFullPathnam
1b480 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  e] method of the
1b490 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   VFS..*/.int sql
1b4a0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
1b4b0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1b4c0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1b4d0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1b4e0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1b4f0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1b500 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1b510 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1b520 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
1b530 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
1b540 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1b550 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1b560 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
1b570 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1b580 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1b590 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1b5a0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1b5b0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
1b5c0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1b5d0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1b5e0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1b5f0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1b600 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
1b610 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1b620 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
1b630 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
1b640 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
1b650 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1b660 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
1b670 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
1b680 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
1b690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
1b6a0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
1b6b0 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d  essages {F12800}
1b6c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1b6d0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1b6e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1b6f0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
1b700 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
1b710 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1b720 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1b730 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1b740 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1b750 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
1b760 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
1b770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1b780 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1b790 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
1b7a0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1b7b0 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1b7c0 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1b7d0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
1b7e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1b7f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1b800 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1b810 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1b820 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1b830 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1b840 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1b850 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1b860 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1b870 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1b880 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1b890 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
1b8a0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1b8b0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1b8c0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1b8d0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1b8e0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1b8f0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1b900 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1b910 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1b920 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1b930 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1b940 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1b950 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1b960 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1b970 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1b980 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1b990 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
1b9a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1b9b0 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12801} The [sqli
1b9c0 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20  te3_errcode(D)] 
1b9d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1b9e0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
1b9f0 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c            [resul
1ba00 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  t code] or [exte
1ba10 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1ba20 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
1ba30 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20  ecently.**      
1ba40 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72      failed inter
1ba50 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69  face call associ
1ba60 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1ba70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ba80 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
1ba90 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2803} The [sqlit
1baa0 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e  e3_errmsg(D)] an
1bab0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
1bac0 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20  g16(D)].**      
1bad0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
1bae0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1baf0 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74  nguage text that
1bb00 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20   describes.**   
1bb10 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72         the error
1bb20 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72   in the mostly r
1bb30 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69  ecently failed i
1bb40 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a  nterface call,.*
1bb50 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64  *          encod
1bb60 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ed as either UTF
1bb70 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1bb80 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
1bb90 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74   {F12807} The st
1bba0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1bbb0 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
1bbc0 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
1bbd0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
1bbe0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
1bbf0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
1bc00 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  xt SQLite interf
1bc10 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ace call..**.** 
1bc20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74  {F12808} Calls t
1bc30 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
1bc40 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
1bc50 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a  n an error code.
1bc60 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61  **          (exa
1bc70 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
1bc80 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
1bc90 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1bca0 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
1bcb0 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67  r code or messag
1bcc0 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1bcd0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1bce0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1bcf0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1bd00 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1bd10 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
1bd20 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72  * {F12809} Inter
1bd30 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
1bd40 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
1bd50 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
1bd60 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1bd70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1bd80 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
1bd90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1bda0 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
1bdb0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1bdc0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
1bdd0 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
1bde0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1bdf0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
1be00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1be10 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
1be20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1be30 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
1be40 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
1be50 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
1be60 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1be70 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1be80 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1be90 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1bea0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1beb0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1bec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bed0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1bee0 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a  bject {F13000}.*
1bef0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1bf00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1bf10 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1bf20 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1bf30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1bf40 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1bf50 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1bf60 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1bf70 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1bf80 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1bf90 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1bfa0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1bfb0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1bfc0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1bfd0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1bfe0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1bff0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1c000 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1c010 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1c020 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1c030 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1c040 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1c050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c060 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1c070 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1c080 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1c090 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1c0a0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1c0b0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1c0c0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1c0d0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1c0e0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1c0f0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1c100 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1c110 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1c120 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1c130 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1c140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1c150 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1c160 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1c170 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1c180 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1c190 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1c1a0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1c1b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1c1c0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1c1d0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1c1e0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1c1f0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1c200 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1c210 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1c220 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1c230 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1c240 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1c250 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1c260 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1c270 69 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a  imits {F12760}.*
1c280 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1c290 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1c2a0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1c2b0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1c2c0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1c2d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1c2e0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1c2f0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1c300 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1c310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c320 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1c330 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1c340 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1c350 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1c360 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1c370 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1c380 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1c390 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1c3a0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1c3b0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1c3c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1c3d0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1c3e0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1c3f0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1c400 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c410 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
1c420 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
1c430 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1c440 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1c450 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1c460 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
1c470 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
1c480 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
1c490 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72  Z there is a har
1c4a0 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64  d upper.** bound
1c4b0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1c4c0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
1c4d0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
1c4e0 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  d SQLITE_MAX_XYZ
1c4f0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1c500 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1c510 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1c520 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d  MAX_".).** Attem
1c530 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1c540 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1c550 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1c560 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1c570 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1c580 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  the hard upper l
1c590 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20  imit..**.** Run 
1c5a0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1c5b0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1c5c0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1c5d0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1c5e0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1c5f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1c600 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
1c610 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
1c620 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
1c630 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
1c640 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
1c650 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
1c660 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
1c670 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74 20  webbrowser that 
1c680 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1c690 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1c6a0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1c6b0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1c6c0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1c6d0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1c6e0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1c6f0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1c700 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1c710 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1c720 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1c730 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1c740 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1c750 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1c760 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1c770 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1c780 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1c790 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1c7a0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1c7b0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1c7c0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1c7d0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1c7e0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1c7f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1c800 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1c810 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1c820 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1c830 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1c840 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1c850 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1c860 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1c870 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1c880 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1c890 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1c8a0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1c8b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1c8c0 72 66 61 63 65 20 69 73 20 63 75 72 72 65 6e 74  rface is current
1c8d0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  ly considered ex
1c8e0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1c8f0 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20  s subject.** to 
1c900 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
1c910 6c 20 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20  l without prior 
1c920 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  notice..**.** IN
1c930 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c940 7b 46 31 32 37 36 32 7d 20 41 20 73 75 63 63 65  {F12762} A succe
1c950 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1c960 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1c970 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a  ,V)] where V is.
1c980 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69  **          posi
1c990 74 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65  tive changes the
1c9a0 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69   limit on the si
1c9b0 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20  ze of construct 
1c9c0 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  C in the.**     
1c9d0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1c9e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20  onnection] D to 
1c9f0 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20  the lesser of V 
1ca00 61 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70  and the hard upp
1ca10 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  er.**          b
1ca20 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65  ound on the size
1ca30 20 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65   of C that is se
1ca40 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1ca50 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 36  e..**.** {F12766
1ca60 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1ca70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1ca80 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68  limit(D,C,V)] wh
1ca90 65 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76  ere V is negativ
1caa0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65  e.**          le
1cab0 61 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f  aves the state o
1cac0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
1cad0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e  connection] D un
1cae0 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
1caf0 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73  F12769} A succes
1cb00 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1cb10 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1cb20 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a  V)] returns the.
1cb30 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
1cb40 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f  e of the limit o
1cb50 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
1cb60 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65  nstruct C in the
1cb70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1cb80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cb90 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70  n] D as it was p
1cba0 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
1cbb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1cbc0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
1cbd0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
1cbe0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
1cbf0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1cc00 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
1cc10 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59   {F12790}.** KEY
1cc20 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1cc30 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
1cc40 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1cc50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1cc60 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1cc70 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
1cc80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cc90 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
1cca0 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
1ccb0 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
1ccc0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
1ccd0 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
1cce0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
1ccf0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
1cd00 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
1cd10 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
1cd20 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1cd30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1cd40 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1cd50 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
1cd60 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
1cd70 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1cd80 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1cd90 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1cda0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1cdb0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
1cdc0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
1cdd0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1cde0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
1cdf0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1ce00 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1ce10 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
1ce20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
1ce30 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
1ce40 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f  et of a SELECT o
1ce50 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1ce60 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1ce70 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1ce80 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1ce90 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1cea0 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
1ceb0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1cec0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1ced0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1cee0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1cef0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1cf00 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1cf10 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1cf20 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1cf30 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1cf40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1cf50 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1cf60 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1cf70 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1cf80 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1cf90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1cfa0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1cfb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1cfc0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1cfd0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1cfe0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1cff0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1d000 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1d010 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1d020 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1d030 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1d040 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1d050 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d060 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1d070 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1d080 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1d090 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1d0a0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1d0b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d0c0 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61  r of attached da
1d0d0 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a  tabases.</dd>.**
1d0e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d0f0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1d100 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
1d110 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1d120 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
1d130 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
1d140 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a  to the LIKE or.*
1d150 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73  * GLOB operators
1d160 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d170 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
1d180 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
1d190 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d1a0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d1b0 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20  variables in an 
1d1c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
1d1d0 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75  at can.** be bou
1d1e0 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  nd.</dd>.** </dl
1d1f0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1d200 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1d210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d220 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1d230 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1d240 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1d250 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1d260 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1d270 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1d280 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1d290 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1d2a0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1d2b0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1d2c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1d2d0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1d2e0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1d2f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1d300 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1d310 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1d320 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d330 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1d340 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1d350 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d360 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1d370 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1d380 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d390 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1d3a0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1d3b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d3c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1d3d0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a  ER           9..
1d3e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d3f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1d400 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 30   Statement {F130
1d410 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10}.** KEYWORDS:
1d420 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1d430 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1d440 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1d450 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1d460 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1d470 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1d480 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1d490 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1d4a0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1d4b0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1d4c0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1d4d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d4e0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1d4f0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1d500 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1d510 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d520 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
1d530 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1d540 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
1d550 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1d560 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1d570 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1d580 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1d590 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1d5a0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1d5b0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1d5c0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1d5d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1d5e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1d5f0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1d600 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1d610 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d620 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1d630 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1d640 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1d650 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1d660 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1d670 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1d680 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1d690 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49  ro terminator. I
1d6a0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1d6b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1d6c0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1d6d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1d6e0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1d6f0 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
1d700 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1d710 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1d720 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1d730 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1d740 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1d750 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1d760 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1d770 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1d780 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1d790 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1d7a0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1d7b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1d7c0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1d7d0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1d7e0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1d7f0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1d800 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1d810 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1d820 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1d830 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1d840 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1d850 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1d860 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1d870 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1d880 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1d890 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69  .**.** *pzTail i
1d8a0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1d8b0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1d8c0 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
1d8d0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53  f the.** first S
1d8e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1d8f0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1d900 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69  tines only compi
1d910 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  le the first.** 
1d920 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1d930 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1d940 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1d950 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a  o what remains.*
1d960 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  * uncompiled..**
1d970 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
1d980 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1d990 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1d9a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d9b0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1d9c0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1d9d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1d9e0 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   If there is an 
1d9f0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1da00 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1da10 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1da20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1da30 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1da40 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1da50 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1da60 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1da70 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1da80 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20  LL..** {A13018} 
1da90 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
1daa0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
1dab0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
1dac0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
1dad0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1dae0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1daf0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
1db00 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1db10 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20   with it..**.** 
1db20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
1db30 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1db40 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ned, otherwise a
1db50 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1db60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1db70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
1db80 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
1db90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1dba0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
1dbb0 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
1dbc0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
1dbd0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
1dbe0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
1dbf0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
1dc00 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
1dc10 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
1dc20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
1dc30 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
1dc40 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
1dc50 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
1dc60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
1dc70 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
1dc80 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
1dc90 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
1dca0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
1dcb0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
1dcc0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
1dcd0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
1dce0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
1dcf0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
1dd00 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
1dd10 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
1dd20 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1dd30 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
1dd40 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1dd50 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1dd60 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1dd70 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1dd80 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1dd90 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1dda0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1ddb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1ddc0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1ddd0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1dde0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1ddf0 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
1de00 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
1de10 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
1de20 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
1de30 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
1de40 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
1de50 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
1de60 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1de70 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
1de80 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
1de90 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c  y behavior, [SQL
1dea0 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a  ITE_SCHEMA] is.*
1deb0 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72  * now a fatal er
1dec0 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73  ror.  Calling [s
1ded0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dee0 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
1def0 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
1df00 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
1df10 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74  Note: use [sqlit
1df20 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20  e3_errmsg()] to 
1df30 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a  find the text.**
1df40 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20   of the parsing 
1df50 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c  error that resul
1df60 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  ts in an [SQLITE
1df70 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e  _SCHEMA] return.
1df80 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1df90 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20  <li>.** When an 
1dfa0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1dfb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1dfc0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1dfd0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1dfe0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1dff0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1e000 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20  or codes].  The 
1e010 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1e020 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1e030 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1e040 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1e050 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1e060 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1e070 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77  ode.** and you w
1e080 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1e090 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1e0a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1e0b0 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  t()] in order.**
1e0c0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1e0d0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1e0e0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
1e0f0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1e100 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
1e110 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1e120 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1e130 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e140 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1e150 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1e160 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1e170 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  TS:.**.** {F1301
1e180 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1e190 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c  prepare(db,zSql,
1e1a0 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
1e1b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1e1c0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1e1d0 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  l,...)] interfac
1e1e0 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  es interpret the
1e1f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
1e200 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20  t in their zSql 
1e210 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46  parameter as UTF
1e220 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  -8..**.** {F1301
1e230 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1e240 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71  prepare16(db,zSq
1e250 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1e260 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1e270 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 62  _prepare16_v2(db
1e280 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1e290 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1e2a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e2b0 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1e2c0 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1e2d0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1e2e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1e2f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d  ..**.** {F13013}
1e300 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1e310 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1e320 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1e330 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
1e340 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
1e350 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
1e360 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1e370 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 69  , the SQL text i
1e380 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  s.**          re
1e390 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20  ad from zSql is 
1e3a0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
1e3b0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1e3c0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ator..**.** {F13
1e3d0 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74  014} If the nByt
1e3e0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1e3f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e400 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1e410 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1e420 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1e430 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ts is non-negati
1e440 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74  ve, then at most
1e450 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f 66   nBytes bytes of
1e460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1e470 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
1e480 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
1e490 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  F13015} In [sqli
1e4a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1e4b0 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
1e4c0 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
1e4d0 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
1e4e0 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
1e4f0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1e500 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
1e510 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1e520 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
1e530 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
1e540 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1e550 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1e560 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
1e570 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
1e580 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1e590 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1e5a0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
1e5b0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1e5c0 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
1e5d0 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
1e5e0 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
1e5f0 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
1e600 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75  ** {F13016} A su
1e610 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1e620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e630 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
1e640 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
1e650 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
1e660 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
1e670 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
1e680 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
1e690 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1e6a0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1e6b0 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
1e6c0 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a  ter to NULL if z
1e6d0 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  Sql contains.** 
1e6e0 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67           nothing
1e6f0 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
1e700 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
1e710 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  ts..**.** {F1301
1e720 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1e730 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
1e740 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
1e750 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
1e760 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1e770 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
1e780 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
1e790 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
1e7a0 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ure..**.** {F130
1e7b0 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69  21} Before [sqli
1e7c0 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
1e7d0 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74  Sql,nByte,ppStmt
1e7e0 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73  ,pzTail)] or its
1e7f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 72  .**          var
1e800 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e  iants returns an
1e810 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75   error (any valu
1e820 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1e830 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20  LITE_OK]),.**   
1e840 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72 73         they firs
1e850 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f  t set *ppStmt to
1e860 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
1e870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1e880 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e890 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1e8a0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1e8b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1e8c0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1e8d0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1e8e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1e8f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1e900 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1e910 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1e920 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1e930 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1e940 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1e950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1e960 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1e970 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1e980 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1e990 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1e9a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1e9b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e9c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1e9d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1e9e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1e9f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ea00 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1ea10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1ea20 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1ea30 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1ea40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1ea50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1ea60 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1ea70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1ea80 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1ea90 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1eaa0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1eab0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1eac0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1ead0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1eae0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1eaf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1eb00 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1eb10 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1eb20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1eb30 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1eb40 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1eb50 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1eb60 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1eb70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1eb80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1eb90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1eba0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1ebb0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1ebc0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1ebd0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1ebe0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1ebf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1ec00 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1ec10 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1ec20 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1ec30 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1ec40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ec50 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1ec60 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1ec70 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1ec80 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1ec90 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1eca0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1ecb0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1ecc0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ecd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ece0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ecf0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1ed00 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1ed10 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1ed20 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1ed30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1ed40 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1ed50 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1ed60 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1ed70 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1ed80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46  ;../*.** CAPIREF
1ed90 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1eda0 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31  tement SQL {F131
1edb0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00}.**.** This i
1edc0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
1edd0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1ede0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1edf0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1ee00 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1ee10 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1ee20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ee30 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
1ee40 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
1ee50 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1ee60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ee70 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1ee80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ee90 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1eea0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
1eeb0 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  01} If the [prep
1eec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1eed0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
1eee0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
1eef0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ef00 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
1ef10 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1ef20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ef30 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  _v2()] or.**    
1ef40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1ef50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
1ef60 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71  then [sqlite3_sq
1ef70 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20  l()] returns.** 
1ef80 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
1ef90 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1efa0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63  minated string c
1efb0 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d  ontaining a UTF-
1efc0 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20  8 rendering.**  
1efd0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f          of the o
1efe0 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74  riginal SQL stat
1eff0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ement..**.** {F1
1f000 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72  3102} If the [pr
1f010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f020 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
1f030 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20  argument to.**  
1f040 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f050 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1f060 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1f070 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f080 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  re()] or.**     
1f090 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1f0a0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
1f0b0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
1f0c0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1f0d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
1f0e0 46 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69  F13103} The stri
1f0f0 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ng returned by [
1f100 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20  sqlite3_sql(S)] 
1f110 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
1f120 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1f130 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f140 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64  nt] S is deleted
1f150 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f160 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f  finalize(S)]..*/
1f170 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1f180 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
1f190 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1f1a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f1b0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
1f1c0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b  d Value Object {
1f1d0 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F15000}.** KEYWO
1f1e0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1f1f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1f200 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1f210 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1f220 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1f230 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1f240 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1f250 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1f260 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1f270 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1f280 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
1f290 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1f2a0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
1f2b0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1f2c0 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69   Values stored i
1f2d0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1f2e0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
1f2f0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
1f300 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1f310 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
1f320 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
1f330 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
1f340 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
1f350 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
1f360 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
1f370 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
1f380 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1f390 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1f3a0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
1f3b0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1f3c0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
1f3d0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
1f3e0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1f3f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1f400 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
1f410 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
1f420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
1f430 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
1f440 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
1f450 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
1f460 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1f470 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
1f480 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
1f490 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
1f4a0 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
1f4b0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
1f4c0 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
1f4d0 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61  held.  A interna
1f4e0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
1f4f0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
1f500 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1f510 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
1f520 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1f530 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
1f540 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1f550 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
1f560 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1f570 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
1f580 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
1f590 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1f5a0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
1f5b0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1f5c0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
1f5d0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ).** then there 
1f5e0 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
1f5f0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1f600 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1f610 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1f620 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
1f630 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
1f640 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
1f650 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
1f660 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
1f670 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
1f680 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1f690 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
1f6a0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
1f6b0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
1f6c0 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70  etween between p
1f6d0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1f6e0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1f6f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f700 73 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 61  s even if they a
1f710 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  re single thread
1f720 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1f730 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1f740 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1f750 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1f760 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1f770 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f780 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1f790 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1f7a0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1f7b0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1f7c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1f7d0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1f7e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1f7f0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1f800 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1f810 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1f820 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1f830 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1f840 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1f850 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1f860 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1f870 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1f880 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1f890 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1f8a0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1f8b0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1f8c0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1f8d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1f8e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1f8f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1f900 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1f910 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1f920 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1f930 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1f940 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54  {F16001}.**.** T
1f950 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
1f960 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
1f970 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
1f980 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
1f990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1f9a0 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
1f9b0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1f9c0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
1f9d0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
1f9e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1f9f0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1fa00 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1fa10 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
1fa20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1fa30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
1fa40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
1fa50 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
1fa60 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
1fa70 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
1fa80 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
1fa90 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
1faa0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1fab0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
1fac0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
1fad0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
1fae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
1faf0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
1fb00 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
1fb10 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
1fb20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
1fb30 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
1fb40 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1fb50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
1fb60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
1fb70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fb80 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1fb90 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1fba0 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a  ments {F13500}.*
1fbb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
1fbc0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
1fbd0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
1fbe0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1fbf0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
1fc00 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
1fc10 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
1fc20 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
1fc30 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
1fc40 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
1fc50 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1fc60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fc70 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1fc80 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
1fc90 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
1fca0 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20   a parameter in 
1fcb0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72  one of these for
1fcc0 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ms:.**.** <ul>.*
1fcd0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
1fce0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
1fcf0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
1fd00 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
1fd10 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
1fd20 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   In the paramete
1fd30 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62  r forms shown ab
1fd40 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e  ove NNN is an in
1fd50 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
1fd60 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20  * and VVV is an 
1fd70 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
1fd80 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68  rameter name. Th
1fd90 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
1fda0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
1fdb0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
1fdc0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1fdd0 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
1fde0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
1fdf0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
1fe00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1fe10 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
1fe20 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
1fe30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1fe40 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
1fe50 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1fe60 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
1fe70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1fe80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1fe90 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1fea0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
1feb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1fec0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
1fed0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1fee0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1fef0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
1ff00 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
1ff10 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65  e set..** The le
1ff20 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
1ff30 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1ff40 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1ff50 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1ff60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1ff70 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1ff80 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1ff90 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1ffa0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1ffb0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1ffc0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1ffd0 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69  rrence..** The i
1ffe0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
1fff0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
20000 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
20010 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20020 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20030 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
20040 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
20050 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
20060 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
20070 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
20080 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c  ..** The NNN val
20090 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
200a0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d  en 1 and the com
200b0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72  pile-time.** par
200c0 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41  ameter SQLITE_MA
200d0 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
200e0 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  R (default value
200f0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
20100 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
20110 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
20120 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
20130 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
20140 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
20150 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
20160 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
20170 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
20180 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20190 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
201a0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
201b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
201c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
201d0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
201e0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
201f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
20200 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
20210 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20220 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
20230 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
20240 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
20250 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20260 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
20270 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
20280 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
20290 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
202a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
202b0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
202c0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
202d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
202e0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
202f0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
20300 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
20310 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
20320 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
20330 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
20340 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
20350 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
20360 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
20370 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
20380 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
20390 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
203a0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
203b0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
203c0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
203d0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
203e0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
203f0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
20400 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
20410 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
20420 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
20430 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
20440 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
20450 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
20460 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
20470 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
20480 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
20490 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
204a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
204b0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
204c0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
204d0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
204e0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
204f0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
20500 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
20510 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
20520 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
20530 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
20540 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
20550 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
20560 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
20570 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
20580 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
20590 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
205a0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
205b0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
205c0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
205d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
205e0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
205f0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
20600 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
20610 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
20620 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
20630 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
20640 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
20650 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20660 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
20670 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
20680 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
20690 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
206a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
206b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
206c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
206d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
206e0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
206f0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
20700 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
20710 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
20720 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
20730 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
20740 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
20750 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
20760 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
20770 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
20780 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
20790 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
207a0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
207b0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
207c0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
207d0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
207e0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
207f0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
20800 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
20810 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
20820 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
20830 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
20840 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
20850 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
20860 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
20870 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20880 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
20890 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
208a0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
208b0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
208c0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
208d0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
208e0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
208f0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
20900 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
20910 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
20920 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
20930 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
20940 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
20950 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
20960 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
20970 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20980 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
20990 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
209a0 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
209b0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
209c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
209d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
209e0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
209f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20a00 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
20a10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
20a20 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20a30 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
20a40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
20a50 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20  13506} The [SQL 
20a60 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
20a70 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74  er] recognizes t
20a80 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
20a90 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22  ms.**          "
20aa0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
20ab0 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
20ac0 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61  "@VVV" as SQL pa
20ad0 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20  rameters,.**    
20ae0 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20        where NNN 
20af0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
20b00 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64  of one or more d
20b10 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  igits.**        
20b20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20    and where VVV 
20b30 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
20b40 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  of one or more a
20b50 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  lphanumeric.**  
20b60 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65          characte
20b70 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
20b80 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
20b90 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  y a string conta
20ba0 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
20bb0 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20    no spaces and 
20bc0 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
20bd0 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
20be0 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65  .** {F13509} The
20bf0 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
20c00 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
20c10 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
20c20 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69  * {F13512} The i
20c30 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
20c40 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
20c50 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
20c60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20c70 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
20c80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
20c90 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
20ca0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
20cb0 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
20cc0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
20cd0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
20ce0 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
20cf0 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
20d00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
20d10 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
20d20 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68  *.** {F13518} Th
20d30 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
20d40 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
20d50 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
20d60 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
20d70 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
20d80 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
20d90 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
20da0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
20db0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
20dc0 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
20dd0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
20de0 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
20df0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
20e00 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
20e10 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
20e20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
20e30 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
20e40 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
20e50 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
20e60 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
20e70 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
20e80 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b  * {F13521} The [
20e90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
20ea0 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69  mpiler] fails wi
20eb0 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41  th an [SQLITE_RA
20ec0 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  NGE].**         
20ed0 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
20ee0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
20ef0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
20f00 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20  than 1.**       
20f10 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68     or greater th
20f20 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  an the compile-t
20f30 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ime SQLITE_MAX_V
20f40 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a  ARIABLE_NUMBER.*
20f50 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
20f60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eter..**.** {F13
20f70 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
20f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20f90 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
20fa0 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
20fb0 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
20fc0 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
20fd0 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
20fe0 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
20ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
21000 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
21010 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21020 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  t] S..**.** {F13
21030 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
21040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21050 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
21060 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
21070 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
21080 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
21090 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
210a0 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
210b0 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69  * {F13530} Bindi
210c0 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
210d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
210e0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
210f0 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
21100 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
21110 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
21120 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21130 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  S)]..**.** {F135
21140 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
21150 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21160 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
21170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21180 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
21190 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
211a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
211b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
211c0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
211d0 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
211e0 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
211f0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
21200 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  OB or string poi
21210 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
21220 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
21230 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21240 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d  ..**.** {F13536}
21250 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21260 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21270 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
21280 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21290 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
212a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
212b0 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
212c0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
212d0 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
212e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
212f0 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
21300 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
21310 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61  * {F13539} In ca
21320 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21330 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
21340 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
21350 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21360 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
21370 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
21380 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21390 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
213a0 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
213b0 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
213c0 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
213d0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
213e0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
213f0 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
21400 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
21410 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
21420 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
21430 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
21440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
21450 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
21460 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
21470 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d  ..**.** {F13542}
21480 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21490 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
214a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
214b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
214c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
214d0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
214e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
214f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
21500 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
21510 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
21520 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
21530 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
21540 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
21550 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20  ine makes a.**  
21560 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
21570 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75  copy of the valu
21580 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65  e V before it re
21590 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  turns..**.** {F1
215a0 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3545} In calls t
215b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
215c0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
215d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
215e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
215f0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
21600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21610 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21620 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
21630 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65  en D is a pointe
21640 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
21650 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c   a function, SQL
21660 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74  ite invokes that
21670 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73   function to des
21680 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  troy the.**     
21690 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74       value V aft
216a0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
216b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c  ed using the val
216c0 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ue V..**.** {F13
216d0 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  548} In calls to
216e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
216f0 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29  eroblob(S,N,V,L)
21700 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e  ] the value boun
21710 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
21720 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74   a BLOB of L byt
21730 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  es, or a zero-le
21740 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69  ngth BLOB if L i
21750 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
21760 2a 20 7b 46 31 33 35 35 31 7d 20 49 6e 20 63 61  * {F13551} In ca
21770 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21780 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56  bind_value(S,N,V
21790 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e  )] the V argumen
217a0 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20  t may.**        
217b0 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70    be either a [p
217c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
217d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f  _value] object o
217e0 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
217f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
21800 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
21810 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
21820 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
21830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21840 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
21850 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
21860 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
21870 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
21880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
21890 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
218a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
218b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
218c0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
218d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
218e0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
218f0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
21900 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
21910 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
21920 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
21930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21940 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
21950 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21960 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
21970 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
21980 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21990 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
219a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
219b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
219c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
219d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
219e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
219f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
21a00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
21a10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21a20 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
21a30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
21a40 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
21a50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
21a60 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
21a70 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13600}.**.** 
21a80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
21a90 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
21aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
21ab0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
21ac0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
21ad0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
21ae0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
21af0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
21b00 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
21b10 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
21b20 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
21b30 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
21b40 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
21b50 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
21b60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21b70 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
21b80 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
21b90 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
21ba0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
21bb0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
21bc0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
21bd0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
21be0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
21bf0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
21c00 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
21c10 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
21c20 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
21c30 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
21c40 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
21c50 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
21c60 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
21c70 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
21c80 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
21c90 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
21ca0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21cb0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
21cc0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
21cd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21ce0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
21cf0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
21d00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21d10 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
21d20 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21d30 20 7b 46 31 33 36 30 31 7d 20 54 68 65 20 5b 73   {F13601} The [s
21d40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21d50 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20  meter_count(S)] 
21d60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
21d70 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
21d80 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
21d90 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  of all SQL param
21da0 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  eters in the.** 
21db0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
21dc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
21dd0 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61   or 0 if S conta
21de0 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
21df0 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
21e00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21e10 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
21e20 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
21e30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
21e40 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
21e50 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a  eter {F13620}.**
21e60 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
21e70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
21e80 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
21e90 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53  f the n-th.** [S
21ea0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
21eb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21ec0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20  tement]..** SQL 
21ed0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
21ee0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
21ef0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
21f00 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
21f10 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
21f20 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
21f30 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
21f40 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
21f50 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
21f60 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
21f70 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
21f80 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
21f90 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
21fa0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
21fb0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
21fc0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
21fd0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
21fe0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
21ff0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
22000 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
22010 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64  re also referred
22020 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75   to as "anonymou
22030 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
22040 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
22050 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
22060 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
22070 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
22080 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
22090 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
220a0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
220b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
220c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
220d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
220e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
220f0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
22100 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
22110 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
22120 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
22130 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
22140 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
22150 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
22160 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
22170 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
22180 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
22190 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
221a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
221b0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
221c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
221d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
221e0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
221f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22200 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
22210 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
22220 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54  **.** {F13621} T
22230 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
22240 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
22250 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22260 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
22270 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64      a UTF-8 rend
22280 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d  ering of the nam
22290 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  e of the SQL par
222a0 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20  ameter in.**    
222b0 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
222c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
222d0 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c   having index N,
222e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
222f0 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
22300 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
22310 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f  r with index N o
22320 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  r if the.**     
22330 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77       parameter w
22340 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61  ith index N is a
22350 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  n anonymous para
22360 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f  meter "?"..*/.co
22370 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22380 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22390 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
223a0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
223b0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
223c0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
223d0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
223e0 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a  me {F13640}.**.*
223f0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64  * Return the ind
22400 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
22410 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
22420 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69   name.  The.** i
22430 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
22440 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
22450 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
22460 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
22470 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
22480 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
22490 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72  _bind()].  A zer
224a0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
224b0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
224c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
224d0 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74  nd.  The paramet
224e0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
224f0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
22500 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
22510 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22520 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
22530 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
22540 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22550 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22560 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22570 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
22580 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22590 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
225a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
225b0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
225c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
225d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
225e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
225f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
22600 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  641} The [sqlite
22610 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22620 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74  _index(S,N)] int
22630 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
22640 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
22650 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
22660 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72  meter in the [pr
22670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22680 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20  ].**          S 
22690 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68  whose name match
226a0 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  es the UTF-8 str
226b0 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74  ing N, or 0 if t
226c0 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20  here is.**      
226d0 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f      no match..*/
226e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
226f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
22700 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
22710 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
22720 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
22730 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
22740 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
22750 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
22760 20 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13660}.**.** 
22770 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
22780 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
22790 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
227a0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
227b0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
227c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
227d0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
227e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
227f0 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73  nt]..** Use this
22800 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
22810 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
22820 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
22830 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
22840 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20  .**.** {F13661} 
22850 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  The [sqlite3_cle
22860 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20  ar_bindings(S)] 
22870 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
22880 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20   all SQL.**     
22890 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62       parameter b
228a0 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b  indings in the [
228b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
228c0 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55  nt] S back to NU
228d0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
228e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
228f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
22900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22910 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
22920 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
22930 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a   Set {F13710}.**
22940 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
22950 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22960 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
22970 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
22980 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
22990 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73  statement]. This
229a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
229b0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
229c0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
229d0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
229e0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
229f0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44  r example an UPD
22a00 41 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ATE)..**.** INVA
22a10 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
22a20 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13711} The [sqli
22a30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
22a40 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
22a50 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
22a60 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
22a70 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
22a80 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72  result set gener
22a90 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 72 65  ated by the [pre
22aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22ab0 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
22ac0 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e  or 0 if S does n
22ad0 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72 65  ot generate a re
22ae0 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  sult set..*/.int
22af0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22b00 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
22b10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
22b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
22b30 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
22b40 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 32  esult Set {F1372
22b50 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
22b60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22b70 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
22b80 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
22b90 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
22ba0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
22bb0 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
22bc0 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
22bd0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
22be0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
22bf0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
22c00 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
22c10 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
22c20 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
22c30 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
22c40 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
22c50 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
22c60 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
22c70 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
22c80 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
22c90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22ca0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
22cb0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
22cc0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
22cd0 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
22ce0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
22cf0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
22d00 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
22d10 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
22d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
22d30 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
22d40 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
22d50 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
22d60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22d70 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
22d80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
22d90 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
22da0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
22db0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
22dc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
22dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22de0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
22df0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
22e00 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
22e10 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
22e20 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
22e30 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
22e40 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
22e50 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
22e60 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
22e70 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
22e80 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
22e90 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
22ea0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
22eb0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
22ec0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
22ed0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
22ee0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
22ef0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
22f00 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
22f10 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
22f20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
22f30 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
22f40 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
22f50 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
22f60 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
22f70 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
22f80 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
22f90 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ext..**.** INVAR
22fa0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
22fb0 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 66  3721} A successf
22fc0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
22fd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
22fe0 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a  lumn_name(S,N)].
22ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
23000 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23010 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74  e name of the Nt
23020 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20  h column (where 
23030 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  0 is.**         
23040 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   the leftmost co
23050 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65  lumn) for the re
23060 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a  sult set of the.
23070 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
23080 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23090 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72   S as a zero-ter
230a0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
230b0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
230c0 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  723} A successfu
230d0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
230e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
230f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
23100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
23110 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
23120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
23130 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
23140 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   0 is.**        
23150 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    the leftmost c
23160 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72  olumn) for the r
23170 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
23180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
23190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
231a0 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  ] S as a zero-te
231b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
231c0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
231d0 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65     in the native
231e0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
231f0 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20  ** {F13724} The 
23200 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23210 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  name()] and [sql
23220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23230 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
23240 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
23250 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
23260 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75  er if they are u
23270 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20  nable to.**     
23280 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65       allocate me
23290 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
232a0 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e  ir normal return
232b0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20   strings..**.** 
232c0 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 65 20  {F13725} If the 
232d0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  N parameter to [
232e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
232f0 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  ame(S,N)] or.** 
23300 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
23310 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
23320 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20  S,N)] is out of 
23330 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a  range, then the.
23340 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
23350 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20  rfaces return a 
23360 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
23370 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54 68 65  .** {F13726} The
23380 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
23390 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
233a0 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  lumn_name(S,N)] 
233b0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
233c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
233d0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65  name16(S,N)] are
233e0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
233f0 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   next.**        
23400 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72    call to either
23410 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68   routine with th
23420 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70  e same S and N p
23430 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
23440 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b        or until [
23450 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23460 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
23470 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57  **.** {F13727} W
23480 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c  hen a result col
23490 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  umn of a [SELECT
234a0 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74  ] statement cont
234b0 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
234c0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74   an AS clause, t
234d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20  he name of that 
234e0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64  column is the id
234f0 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20  entifier.**     
23500 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68       to the righ
23510 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77  t of the AS keyw
23520 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ord..*/.const ch
23530 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
23540 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
23550 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
23560 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23570 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23590 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
235a0 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
235b0 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
235c0 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34  ry Result {F1374
235d0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
235e0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
235f0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
23600 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
23610 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
23620 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
23630 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
23640 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
23650 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
23660 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
23670 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
23680 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
23690 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
236a0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
236b0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
236c0 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
236d0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
236e0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
236f0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
23700 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
23710 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
23720 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
23730 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
23740 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
23750 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
23760 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
23770 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
23780 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23790 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
237a0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
237b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
237c0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
237d0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
237e0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
237f0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
23800 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
23810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
23820 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
23830 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
23840 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
23850 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
23860 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
23870 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
23880 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
23890 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
238a0 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
238b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
238c0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
238d0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
238e0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
238f0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
23900 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
23910 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
23920 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
23930 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
23940 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
23950 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
23960 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
23970 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
23980 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
23990 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
239a0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
239b0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
239c0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
239d0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  .** NULL.  These
239e0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
239f0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
23a00 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
23a10 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
23a20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
23a30 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
23a40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23a50 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
23a60 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20  e, table.** and 
23a70 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
23a80 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
23a90 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
23aa0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
23ab0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
23ac0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
23ad0 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
23ae0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
23af0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
23b00 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
23b10 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
23b20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  UTF-8. {END}.**.
23b30 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
23b40 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
23b50 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
23b60 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
23b70 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
23b80 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
23b90 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
23ba0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
23bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35  ed..**.** {A1375
23bc0 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  1}.** If two or 
23bd0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
23be0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
23bf0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
23c00 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
23c10 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
23c20 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
23c30 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
23c40 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
23c50 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
23c60 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ined..**.** INVA
23c70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
23c80 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  13741} The [sqli
23c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23ca0 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ase_name(S,N)] i
23cb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23cc0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
23cd0 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
23ce0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
23cf0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
23d00 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  se from which th
23d10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
23d20 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
23d30 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
23d40 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
23d50 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20   extracted,.**  
23d60 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
23d70 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
23d80 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
23d90 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
23da0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
23db0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
23dc0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
23dd0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
23de0 0a 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54 68 65  .** {F13742} The
23df0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23e00 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
23e10 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23e20 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23e30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23e40 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
23e50 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65  te order zero-te
23e60 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
23e70 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
23e80 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77            from w
23e90 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
23ea0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
23eb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23ec0 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20  ement] S is.**  
23ed0 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65          extracte
23ee0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
23ef0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
23f00 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
23f10 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
23f20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
23f30 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
23f40 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
23f50 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
23f60 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c  F13743} The [sql
23f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
23f80 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
23f90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
23fa0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
23fb0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
23fc0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
23fd0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72   of the table fr
23fe0 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
23ff0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
24000 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
24010 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24020 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
24030 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
24040 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
24050 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
24060 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
24070 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
24080 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
24090 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
240a0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
240b0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
240c0 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c  F13744} The [sql
240d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
240e0 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
240f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24100 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24110 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
24120 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
24130 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24140 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
24150 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  le.**          f
24160 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
24170 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
24180 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
24190 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
241a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74  .**          ext
241b0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
241c0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
241d0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
241e0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
241f0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
24200 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
24210 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
24220 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
24230 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54 68 65  .** {F13745} The
24240 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24250 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e  _origin_name(S,N
24260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24270 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
24280 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
24290 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
242a0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
242b0 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20  ble column from 
242c0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
242d0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
242e0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
242f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24300 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
24310 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
24320 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
24330 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
24340 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
24350 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
24360 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
24370 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
24380 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
24390 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  name..**.** {F13
243a0 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  746} The [sqlite
243b0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
243c0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
243d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
243e0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
243f0 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
24400 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
24410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
24420 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
24430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
24440 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74  umn from which t
24450 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
24460 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20  lumn of the.**  
24470 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
24480 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
24490 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20  s extracted, or 
244a0 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
244b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
244c0 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e     of S is a gen
244d0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
244e0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
244f0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
24500 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
24510 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
24520 2a 0a 2a 2a 20 7b 46 31 33 37 34 38 7d 20 54 68  *.** {F13748} Th
24530 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20  e return values 
24540 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  from.**         
24550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24560 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
24570 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
24580 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
24590 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
245a0 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74  id for the lifet
245b0 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  ime of the [prep
245c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
245d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
245e0 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e  ntil the encodin
245f0 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20  g is changed by 
24600 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61  another metadata
24610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
24620 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20  erface call for 
24630 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65  the same prepare
24640 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
24650 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49  column..**.** LI
24660 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
24670 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f   {A13751} If two
24680 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
24690 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
246a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
246b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
246c0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
246d0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
246e0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20  terfaces].**    
246f0 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73 61        for the sa
24700 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
24710 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
24720 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20  lt column.**    
24730 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d        at the sam
24740 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
24750 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
24760 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
24770 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
24780 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
24790 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
247a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
247b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
247c0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
247d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
247e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
247f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24800 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
24810 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
24820 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
24830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
24840 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
24850 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
24860 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24870 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
24880 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
24890 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
248a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
248b0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
248c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
248d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
248e0 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
248f0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
24900 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30  y Result {F13760
24910 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  }.**.** The firs
24920 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
24930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24940 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
24950 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
24960 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
24970 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
24980 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
24990 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
249a0 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43  et of that SELEC
249b0 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  T is a table col
249c0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
249d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
249e0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
249f0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
24a00 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
24a10 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
24a20 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
24a30 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
24a40 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
24a50 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
24a60 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
24a70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
24a80 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
24a90 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24aa0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
24ab0 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a  encoded. {END}.*
24ac0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
24ad0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
24ae0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
24af0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
24b00 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
24b10 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
24b20 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
24b30 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
24b40 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
24b50 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
24b60 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
24b70 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
24b80 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
24b90 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
24ba0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
24bb0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
24bc0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
24bd0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
24be0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
24bf0 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
24c00 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
24c10 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
24c20 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
24c30 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
24c40 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
24c50 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
24c60 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
24c70 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
24c80 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
24c90 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
24ca0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
24cb0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
24cc0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
24cd0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
24ce0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
24cf0 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
24d00 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
24d10 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
24d20 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
24d30 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
24d40 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
24d50 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
24d60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
24d70 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20  .**.** {F13761} 
24d80 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
24d90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
24da0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
24db0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a  ,N)] returns a.*
24dc0 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  *           zero
24dd0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
24de0 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
24df0 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64  ing the declared
24e00 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20   datatype.**    
24e10 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61         of the ta
24e20 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
24e30 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e  appears as the N
24e40 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
24e50 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
24e60 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
24e70 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
24e80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24e90 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
24ea0 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {F13762}  A succ
24eb0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
24ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24ed0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
24ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
24ef0 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
24f00 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
24f10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
24f20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
24f30 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
24f40 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
24f50 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
24f60 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
24f70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
24f80 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
24f90 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
24fa0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
24fb0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
24fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
24fd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24fe0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
24ff0 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
25000 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
25010 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
25020 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
25030 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
25040 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25050 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25060 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
25070 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74           or if t
25080 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
25090 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73   S is an express
250a0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20  ion or subquery 
250b0 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  rather.**       
250c0 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65      than a table
250d0 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61   column, or if a
250e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
250f0 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20  on failure.**   
25100 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
25110 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63  uring encoding c
25120 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e  onversions, then
25130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
25140 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
25150 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
25160 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
25170 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
25180 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
25190 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55  (S,N)] return NU
251a0 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  LL..*/.const cha
251b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
251c0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
251d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
251e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
251f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
25200 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
25210 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
25220 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
25230 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
25240 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a  ent {F13200}.**.
25250 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
25260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25270 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
25280 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
25290 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
252a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
252b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
252c0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
252d0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
252e0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
252f0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
25300 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25310 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
25320 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
25330 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
25340 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
25350 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
25360 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
25370 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
25380 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
25390 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
253a0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
253b0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
253c0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
253d0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
253e0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
253f0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
25400 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
25410 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
25420 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
25430 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
25440 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
25450 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
25460 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
25470 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
25480 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
25490 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
254a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
254b0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
254c0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
254d0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
254e0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
254f0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
25500 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67  **.** In the leg
25510 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
25520 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
25530 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
25540 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
25550 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
25560 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
25570 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
25580 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
25590 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
255a0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
255b0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
255c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
255d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
255e0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
255f0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
25600 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
25610 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
25620 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
25630 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
25640 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
25650 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
25660 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
25670 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
25680 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
25690 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f  is a COMMIT.** o
256a0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
256b0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
256c0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
256d0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
256e0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
256f0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
25700 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d  ent is not a COM
25710 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77  MIT and occurs w
25720 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
25730 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
25740 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
25750 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
25760 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
25770 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
25780 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
25790 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
257a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
257b0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
257c0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
257d0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
257e0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
257f0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
25800 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
25810 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
25820 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
25830 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25840 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
25850 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
25860 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
25870 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
25880 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
25890 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
258a0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
258b0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
258c0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
258d0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
258e0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
258f0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
25900 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
25910 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
25920 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
25930 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
25940 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
25950 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
25960 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
25970 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
25980 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
25990 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
259a0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
259b0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
259c0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
259d0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
259e0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
259f0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
25a00 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
25a10 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
25a20 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
25a30 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
25a40 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
25a50 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
25a60 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
25a70 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
25a80 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
25a90 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
25aa0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
25ab0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
25ac0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
25ad0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
25ae0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
25af0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
25b00 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
25b10 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
25b20 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
25b30 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
25b40 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
25b50 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
25b60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
25b70 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
25b80 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
25b90 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
25ba0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
25bb0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
25bc0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
25bd0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
25be0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
25bf0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
25c00 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
25c10 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
25c20 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
25c30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
25c40 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
25c50 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
25c60 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
25c70 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
25c80 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
25c90 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
25ca0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
25cb0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
25cc0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
25cd0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
25ce0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
25cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
25d00 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
25d10 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
25d20 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
25d30 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
25d40 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
25d50 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
25d60 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
25d70 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
25d80 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
25d90 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
25da0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
25db0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
25dc0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
25dd0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
25de0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
25df0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
25e00 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
25e10 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
25e20 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
25e30 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
25e40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
25e50 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
25e60 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
25e70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
25e80 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
25e90 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
25ea0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
25eb0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
25ec0 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
25ed0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
25ee0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
25ef0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
25f00 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
25f10 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
25f20 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
25f30 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
25f40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25f50 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
25f60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
25f70 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
25f80 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
25f90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25fa0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
25fb0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
25fc0 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
25fd0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
25fe0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
25ff0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
26000 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
26010 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
26020 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
26030 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
26040 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
26050 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26060 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66 20  ** {F13202}  If 
26070 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26080 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
26090 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74  ady to be run, t
260a0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
260b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
260c0 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
260d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
260e0 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ent until.**    
260f0 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f         completio
26100 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
26110 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
26120 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
26130 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26140 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20   result set, or 
26150 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
26160 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
26170 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20  terrupt].**     
26180 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74        or a run-t
26190 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ime error occurs
261a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d  ..**.** {F15304}
261b0 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
261c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
261d0 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70  )] causes the [p
261e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
261f0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
26200 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
26210 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63  letion, the func
26220 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
26230 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
26240 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 68 65 6e  * {F15306}  When
26250 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
26260 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f  te3_step(S)] sto
26270 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ps because it is
26280 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20   ready to.**    
26290 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e         return an
262a0 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
262b0 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20   result set, it 
262c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
262d0 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ROW]..**.** {F15
262e0 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
262f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26300 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
26310 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
26320 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
26330 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
26340 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
26350 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
26360 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
26370 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
26380 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
26390 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
263a0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
263b0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
263c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
263d0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31  E]..**.** {F1531
263e0 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
263f0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
26400 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
26410 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
26420 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
26430 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
26440 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26450 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
26460 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
26470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
26480 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
26490 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
264a0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
264b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
264c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
264d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
264e0 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
264f0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
26500 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
26510 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
26520 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
26530 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
26540 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
26550 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
26560 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
26570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26580 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26590 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
265a0 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13770}.**.** Re
265b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
265c0 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
265d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
265e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
265f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
26600 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31  S:.**.** {F13771
26610 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20  }  After a call 
26620 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26630 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e  (S)] that return
26640 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a  s [SQLITE_ROW],.
26650 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
26660 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
26670 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65  ount(S)] routine
26680 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
26690 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20   same value.**  
266a0 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
266b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
266c0 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69  count(S)] functi
266d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37  on..**.** {F1377
266e0 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74  2}  After [sqlit
266f0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
26700 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c  returned any val
26710 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
26720 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
26730 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72  TE_ROW] or befor
26740 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
26750 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  S)] has been cal
26760 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20  led on the.**   
26770 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
26780 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72  d statement] for
26790 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
267a0 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20  since it was.** 
267b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
267c0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
267d0 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74  pared] or [sqlit
267e0 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74  e3_reset | reset
267f0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
26800 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
26810 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74  a_count(S)] rout
26820 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
26830 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
26840 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
26850 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
26860 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26870 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
26880 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35  atatypes {F10265
26890 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  }.** KEYWORDS: S
268a0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
268b0 20 7b 46 31 30 32 36 36 7d 20 45 76 65 72 79 20   {F10266} Every 
268c0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
268d0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
268e0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
268f0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
26900 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
26910 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
26920 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
26930 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
26940 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
26950 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
26960 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
26970 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
26980 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
26990 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
269a0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
269b0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
269c0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
269d0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
269e0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
269f0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
26a00 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
26a10 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
26a20 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
26a30 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
26a40 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
26a50 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
26a60 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
26a70 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
26a80 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
26a90 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
26aa0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
26ab0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
26ac0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
26ad0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
26ae0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
26af0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
26b00 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
26b10 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
26b20 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
26b30 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
26b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
26b50 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
26b60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
26b70 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
26b80 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
26b90 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
26ba0 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a  Query {F13800}.*
26bb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
26bc0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
26bd0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
26be0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
26bf0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
26c00 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
26c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
26c20 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
26c30 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
26c40 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
26c50 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
26c60 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
26c70 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
26c80 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
26c90 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
26ca0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
26cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26cc0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
26cd0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
26ce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
26cf0 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
26d00 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
26d10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26d20 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
26d30 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
26d40 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
26d50 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
26d60 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
26d70 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
26d80 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
26d90 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
26da0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
26db0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
26dc0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
26dd0 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66  ndex 0..**.** If
26de0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
26df0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
26e00 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
26e10 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
26e20 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
26e30 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
26e40 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
26e50 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
26e60 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26e70 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
26e80 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
26e90 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
26ea0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
26eb0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
26ec0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
26ed0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
26ee0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26ef0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
26f00 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
26f10 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
26f20 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
26f30 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
26f40 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
26f50 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
26f60 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
26f70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26f80 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
26f90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
26fa0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
26fb0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
26fc0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
26fd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
26fe0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
26ff0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27000 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
27010 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
27020 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
27030 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
27040 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
27050 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
27060 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
27070 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
27080 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
27090 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
270a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
270b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
270c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
270d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
270e0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
270f0 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
27100 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
27110 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
27120 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65  ult column.  The
27130 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
27140 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
27150 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
27160 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
27170 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
27180 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
27190 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
271a0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
271b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
271c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
271d0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
271e0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
271f0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
27200 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
27210 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
27220 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
27230 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
27240 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
27250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27260 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
27270 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
27280 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
27290 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
272a0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
272b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
272c0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
272d0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
272e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
272f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
27300 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
27310 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
27320 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27330 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
27340 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
27350 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
27360 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
27370 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
27380 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
27390 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
273a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
273b0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
273c0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
273d0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
273e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
273f0 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68   bytes..** If th
27400 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
27410 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
27420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27430 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
27440 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
27450 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
27460 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
27470 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
27480 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
27490 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
274a0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
274b0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
274c0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
274d0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
274e0 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
274f0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
27500 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61  string.  For cla
27510 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
27520 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
27530 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
27540 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
27550 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
27560 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
27570 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65  **.** Strings re
27580 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
27590 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
275a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
275b0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
275c0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
275d0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
275e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
275f0 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
27600 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
27610 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
27620 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
27630 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62  h BLOB is an arb
27640 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
27650 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
27660 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
27670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27680 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27690 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
276a0 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
276b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
276c0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
276d0 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
276e0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
276f0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
27700 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68   of UTF-8..** Th
27710 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
27720 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  r is not include
27730 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e  d in this count.
27740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63  .**.** The objec
27750 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
27760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
27770 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
27780 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
27790 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
277a0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
277b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
277c0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
277d0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
277e0 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
277f0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
27800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
27810 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
27820 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
27830 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27840 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
27850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
27860 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
27870 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
27880 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
27890 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
278a0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
278b0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
278c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
278d0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
278e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
278f0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
27900 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
27910 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
27920 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
27930 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
27940 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
27950 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f  appropriate.  Fo
27960 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
27970 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
27980 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
27990 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
279a0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
279b0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
279c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
279d0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
279e0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
279f0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
27a00 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
27a10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
27a20 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
27a30 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
27a40 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
27a50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
27a60 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
27a70 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
27a80 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
27a90 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
27aa0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
27ab0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
27ac0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
27ad0 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
27ae0 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
27af0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
27b00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
27b10 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
27b20 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
27b30 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
27b40 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
27b50 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
27b60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
27b70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
27b80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
27b90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
27ba0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
27bb0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
27bc0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
27bd0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
27be0 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
27bf0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
27c00 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
27c10 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
27c20 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
27c30 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
27c40 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
27c50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
27c60 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
27c70 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
27c80 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
27c90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
27ca0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
27cb0 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
27cc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
27cd0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
27ce0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
27cf0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
27d00 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
27d10 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
27d20 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
27d30 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
27d40 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
27d50 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
27d60 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
27d70 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
27d80 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
27d90 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
27da0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
27db0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
27dc0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
27dd0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
27de0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
27df0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
27e00 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
27e10 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
27e20 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
27e30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
27e40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
27e50 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
27e60 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
27e70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
27e80 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
27e90 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
27ea0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
27eb0 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
27ec0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
27ed0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
27ee0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
27ef0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
27f00 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
27f10 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
27f20 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
27f30 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
27f40 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
27f50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
27f60 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
27f70 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
27f80 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
27f90 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
27fa0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
27fb0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
27fc0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
27fd0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
27fe0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
27ff0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
28000 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
28010 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
28020 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
28030 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
28040 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
28050 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
28060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
28070 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
28080 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
28090 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
280a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
280b0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
280c0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
280d0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
280e0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
280f0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
28100 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
28110 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
28120 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
28130 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
28140 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
28150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28160 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
28170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28180 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
28190 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
281a0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
281b0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
281c0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
281d0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
281e0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
281f0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
28200 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
28210 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
28220 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
28230 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28240 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
28250 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
28260 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
28270 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
28280 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
28290 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
282a0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
282b0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
282c0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
282d0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
282e0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
282f0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
28300 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
28310 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
28320 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
28330 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72  ul>.**.** Conver
28340 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
28350 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
28360 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
28370 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
28380 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
28390 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
283a0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
283b0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
283c0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
283d0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
283e0 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e  ior pointer poin
283f0 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20  ts to will have 
28400 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
28410 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
28420 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
28430 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
28440 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
28450 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
28460 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
28470 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
28480 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
28490 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
284a0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
284b0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
284c0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
284d0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
284e0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
284f0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
28500 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
28510 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
28520 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
28530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28540 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
28550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28560 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
28570 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
28580 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
28590 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
285a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
285b0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
285c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
285d0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
285e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
285f0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
28600 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
28610 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
28620 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
28630 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
28640 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
28650 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
28660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28670 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
28680 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
28690 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
286a0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
286b0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
286c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
286d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
286e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
286f0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
28700 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
28710 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
28720 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
28730 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
28740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28750 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
28760 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
28770 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
28780 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
28790 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
287a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
287b0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
287c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
287d0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
287e0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
287f0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
28800 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
28810 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
28820 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
28830 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
28840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28850 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
28860 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
28870 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
28880 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
28890 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
288a0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
288b0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
288c0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
288d0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
288e0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
288f0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
28900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
28910 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
28920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28930 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
28940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
28950 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
28960 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
28970 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
28980 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
28990 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
289a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
289b0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
289c0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
289d0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
289e0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
289f0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
28a00 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
28a10 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
28a20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
28a30 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
28a40 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
28a50 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
28a60 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
28a70 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
28a80 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
28a90 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20  ** {F13803} The 
28aa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28ab0 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
28ac0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28ad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
28ae0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
28af0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
28b00 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
28b10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
28b20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28b30 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
28b40 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65  BLOB and then re
28b50 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
28b60 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74      pointer to t
28b70 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
28b80 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  ue..**.** {F1380
28b90 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
28ba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e  column_bytes(S,N
28bb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28bc0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
28bd0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
28be0 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42  ytes in the BLOB
28bf0 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
28c00 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
28c10 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
28c20 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
28c30 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
28c40 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
28c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
28c60 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
28c70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28c80 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _blob(S,N)] or.*
28c90 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
28ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28cb0 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  S,N)]..**.** {F1
28cc0 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3809} The [sqlit
28cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28ce0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
28cf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
28d00 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
28d10 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
28d20 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
28d30 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
28d40 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
28d50 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
28d60 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
28d70 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
28d80 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
28d90 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
28da0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28db0 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  xt16(S,N)]..**.*
28dc0 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b  * {F13812} The [
28dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28de0 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65  ouble(S,N)] inte
28df0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28e00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
28e10 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
28e20 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
28e30 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
28e40 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
28e50 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
28e60 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
28e70 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28e80 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
28e90 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
28ea0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
28eb0 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31  ue..**.** {F1381
28ec0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
28ed0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d  column_int(S,N)]
28ee0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28ef0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
28f00 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
28f10 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
28f20 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
28f30 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
28f40 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
28f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
28f60 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
28f70 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
28f80 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
28f90 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
28fa0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
28fb0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
28fc0 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  3818} The [sqlit
28fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
28fe0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
28ff0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
29000 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
29010 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
29020 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
29030 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
29040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
29050 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29060 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
29070 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
29080 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
29090 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
290a0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
290b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20  .**.** {F13821} 
290c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
290d0 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
290e0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
290f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
29100 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
29110 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29120 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29130 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
29140 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
29150 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
29160 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
29170 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ted UTF-8.**    
29180 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
29190 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
291a0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
291b0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34  g..**.** {F13824
291c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
291d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
291e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
291f0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
29200 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
29210 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29220 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29230 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
29240 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
29250 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29260 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
29270 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
29280 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
29290 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
292a0 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69   byte order stri
292b0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
292c0 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69  *          a poi
292d0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
292e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ing..**.** {F138
292f0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
29300 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e  _column_type(S,N
29310 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
29320 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
29330 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
29340 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
29350 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
29360 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
29370 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
29380 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
29390 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
293a0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
293b0 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75      the Nth colu
293c0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
293d0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
293e0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
293f0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
29400 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29410 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33   S..**.** {F1383
29420 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
29430 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e  column_value(S,N
29440 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
29450 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
29460 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e     pointer to an
29470 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
29480 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29490 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ect for the.**  
294a0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
294b0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
294c0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
294d0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
294e0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
294f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29500 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69   S..*/.const voi
29510 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29520 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
29530 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
29550 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
29560 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
29570 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
29580 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
29590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
295a0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
295b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
295c0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
295d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
295e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
295f0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
29600 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29610 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
29620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
29630 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
29640 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
29650 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
29660 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29670 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
29680 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29690 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
296a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
296b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
296c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
296d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
296e0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
296f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
29700 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
29710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
29720 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
29730 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
29740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
29750 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
29760 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
29770 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13300}.**.**
29780 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
29790 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
297a0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
297b0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
297c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
297d0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
297e0 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
297f0 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
29800 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
29810 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
29820 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
29830 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  . If execution o
29840 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
29850 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a  failed then an.*
29860 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
29870 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
29880 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
29890 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
298a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
298b0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
298c0 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
298d0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
298e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
298f0 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20  ement].  If the 
29900 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
29910 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
29920 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
29930 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
29940 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
29950 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
29960 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
29970 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
29980 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
29990 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f  errupt]..** Inco
299a0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
299b0 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
299c0 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
299d0 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
299e0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
299f0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
29a00 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
29a10 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
29a20 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
29a30 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
29a40 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
29a50 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {F11302} The [s
29a60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29a70 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
29a80 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
29a90 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
29aa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
29ab0 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
29ac0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
29ad0 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
29ae0 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
29af0 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
29b00 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {F11304} If the 
29b10 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
29b20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
29b30 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
29b40 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
29b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29b60 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
29b70 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
29b80 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
29b90 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
29ba0 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
29bb0 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
29bc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
29bd0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
29be0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29bf0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
29c00 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
29c10 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a  ject {F13330}.**
29c20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29c30 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
29c40 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
29c50 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
29c60 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
29c70 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
29c80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
29c90 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
29ca0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
29cb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
29cc0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
29cd0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
29ce0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
29cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
29d00 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
29d10 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
29d20 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
29d30 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
29d40 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
29d50 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
29d60 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
29d70 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b  * {F11332} The [
29d80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
29d90 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
29da0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
29db0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
29dc0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
29dd0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
29de0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
29df0 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49  **.** {F11334} I
29e00 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
29e10 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29e20 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
29e30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29e40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29e50 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
29e60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
29e70 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
29e80 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
29e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29ea0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
29eb0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
29ec0 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
29ed0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
29ee0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
29ef0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
29f00 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66  *.** {F11336} If
29f10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
29f20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29f30 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
29f40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
29f50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29f60 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
29f70 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
29f80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
29f90 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
29fa0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
29fb0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
29fc0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38  ]..**.** {F11338
29fd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
29fe0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
29ff0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2a000 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2a010 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
2a020 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a030 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2a040 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a050 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2a060 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2a070 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a080 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a090 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2a0a0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2a0b0 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31 30  Functions {F1610
2a0c0 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
2a0d0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
2a0e0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
2a0f0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2a100 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2a110 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
2a120 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2a130 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2a140 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
2a150 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75  .** These two fu
2a160 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2a170 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2a180 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2a190 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2a1a0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2a1b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2a1c0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2a1d0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2a1e0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2a1f0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2a200 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2a210 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2a220 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e  fference between
2a230 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74   the.** two is t
2a240 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70  hat the second p
2a250 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61  arameter, the na
2a260 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
2a270 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  r) function or.*
2a280 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20  * aggregate, is 
2a290 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
2a2a0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2a2b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
2a2c0 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72  nd UTF-16.** for
2a2d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a2e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  function16()..**
2a2f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
2a300 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2a310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a320 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2a330 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2a340 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2a350 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70  .  If a single p
2a360 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65  rogram uses more
2a370 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2a380 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2a390 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65   internally, the
2a3a0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  n SQL functions 
2a3b0 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e  must be added in
2a3c0 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a  dividually to.**
2a3d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2a3e0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onnection..**.**
2a3f0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
2a400 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2a410 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2a420 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2a430 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2a440 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68  ned.  The length
2a450 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2a460 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2a470 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20  ytes, exclusive 
2a480 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74  of.** the zero-t
2a490 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
2a4a0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
2a4b0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2a4c0 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
2a4d0 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
2a4e0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
2a4f0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
2a500 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
2a510 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
2a520 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  in [SQLITE_ERROR
2a530 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2a540 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
2a550 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2a560 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2a570 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2a580 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2a590 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2a5a0 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
2a5b0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
2a5c0 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
2a5d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2a5e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2a5f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2a600 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2a610 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2a620 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2a630 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2a640 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2a650 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2a660 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2a670 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2a680 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2a690 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
2a6a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2a6b0 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
2a6c0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
2a6d0 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
2a6e0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2a6f0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2a700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2a710 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2a720 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2a730 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2a740 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
2a750 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
2a760 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2a770 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2a780 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a790 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2a7a0 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2a7b0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2a7c0 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2a7d0 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2a7e0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2a7f0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2a800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2a810 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2a820 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2a830 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2a840 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2a850 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2a860 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2a870 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2a880 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2a890 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2a8a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2a8b0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2a8c0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2a8d0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2a8e0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2a8f0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2a900 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2a910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
2a920 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2a930 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2a940 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2a950 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2a960 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2a970 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2a980 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2a990 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2a9a0 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
2a9b0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
2a9c0 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
2a9d0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2a9e0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2a9f0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2aa00 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2aa10 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2aa20 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2aa30 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2aa40 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
2aa50 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2aa60 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2aa70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2aa80 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2aa90 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
2aaa0 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
2aab0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2aac0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2aad0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2aae0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2aaf0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2ab00 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2ab10 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2ab20 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2ab30 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
2ab40 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2ab50 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
2ab60 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2ab70 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2ab80 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
2ab90 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2aba0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
2abb0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
2abc0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2abd0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2abe0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2abf0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2ac00 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2ac10 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2ac20 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2ac30 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2ac40 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2ac50 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2ac60 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2ac70 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
2ac80 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
2ac90 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
2aca0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2acb0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2acc0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2acd0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
2ace0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2acf0 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20  ** {F16103} The 
2ad00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ad10 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e  function16()] in
2ad20 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20  terface behaves 
2ad30 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
2ad40 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65      like [sqlite
2ad50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ad60 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61  n()] in every wa
2ad70 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  y except that it
2ad80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2ad90 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e  erprets the zFun
2ada0 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65  ctionName argume
2adb0 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  nt as zero-termi
2adc0 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20  nated UTF-16.** 
2add0 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20           native 
2ade0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
2adf0 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65  ad of as zero-te
2ae00 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a  rminated UTF-8..
2ae10 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41  **.** {F16106} A
2ae20 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
2ae30 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  cation of.**    
2ae40 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2ae50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ae60 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2ae70 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2ae80 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2ae90 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c   or replaces cal
2aea0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
2aeb0 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
2aec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
2aed0 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20  *          used 
2aee0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
2aef0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2af00 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
2af10 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
2af20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61      and having a
2af30 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2af40 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a  encoding of E..*
2af50 2a 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20  *.** {F16109} A 
2af60 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2af70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2af80 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2af90 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2afa0 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63            replac
2afb0 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20  es the P, F, S, 
2afc0 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f  and L values fro
2afd0 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  m any prior call
2afe0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
2aff0 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58     the same D, X
2b000 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65  , N, and E value
2b010 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32  s..**.** {F16112
2b020 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2b030 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2b040 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,X,...)] interfa
2b050 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a  ce fails with.**
2b060 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
2b070 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
2b080 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65  TE_ERROR] if the
2b090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2b0a0 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20  me X is.**      
2b0b0 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20      longer than 
2b0c0 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73  255 bytes exclus
2b0d0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20  ive of the zero 
2b0e0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2b0f0 2a 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65  * {F16118} Eithe
2b100 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c  r F must be NULL
2b110 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
2b120 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73   non-NULL or els
2b130 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e F.**          
2b140 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20  is non-NULL and 
2b150 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c  S and L are NULL
2b160 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20  , otherwise.**  
2b170 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2b180 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b190 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2b1a0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2b1b0 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a  TE_ERROR]..**.**
2b1c0 20 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {F16121} The [s
2b1d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b1e0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
2b1f0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
2b200 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
2b210 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
2b220 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
2b230 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70  f there exist [p
2b240 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b250 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts].**          
2b260 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b270 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b280 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
2b290 2a 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20  ** {F16124} The 
2b2a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b2b0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2b2c0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
2b2d0 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2b2e0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2b2f0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
2b300 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74  RROR] if paramet
2b310 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67  er N (specifying
2b320 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
2b330 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d          of argum
2b340 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
2b350 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72  function being r
2b360 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65  egistered) is le
2b370 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
2b380 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2b390 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
2b3a0 2a 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20  * {F16127} When 
2b3b0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2b3c0 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
2b3d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b3e0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2b3f0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2b400 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
2b410 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2b420 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
2b430 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2b440 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74    named X when t
2b450 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2b460 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2b470 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  L function is.**
2b480 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c            exactl
2b490 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  y N..**.** {F161
2b4a0 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31  30} When N is -1
2b4b0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
2b4c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2b4d0 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2b4e0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2b4f0 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
2b500 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
2b510 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63  for the SQL func
2b520 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2b530 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e   named X with an
2b540 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2b550 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ments..**.** {F1
2b560 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6133} When calls
2b570 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2b580 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2b590 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2b5a0 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c       specify mul
2b5b0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2b5c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2b5d0 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  e function X.** 
2b5e0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
2b5f0 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n one implementa
2b600 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e  tion has N>=0 an
2b610 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20  d the other has 
2b620 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20  N=(-1).**       
2b630 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74     the implement
2b640 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2b650 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65  -zero N is prefe
2b660 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
2b670 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  136} When calls 
2b680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2b690 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2b6a0 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,E,...)].**    
2b6b0 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2b6c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2b6d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2b6e0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  me function X wi
2b6f0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2b700 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
2b710 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75  f arguments N bu
2b720 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
2b730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
2b740 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74  odings E, then t
2b750 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2b760 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65  n where E matche
2b770 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2b780 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64    database encod
2b790 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64  ing is preferred
2b7a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d  ..**.** {F16139}
2b7b0 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
2b7c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
2b7d0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
2b7e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2b7f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b800 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
2b810 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65  L)] the finalize
2b820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  r.**          fu
2b830 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c  nction L will al
2b840 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20  ways be invoked 
2b850 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20  exactly once if 
2b860 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2b870 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20  step function S 
2b880 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  is called one or
2b890 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a   more times..**.
2b8a0 2a 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65 6e  ** {F16142} When
2b8b0 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
2b8c0 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63  either the xFunc
2b8d0 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69   or xStep functi
2b8e0 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  on of.**        
2b8f0 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    an application
2b900 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2b910 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2b920 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20  te created.**   
2b930 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
2b940 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b950 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  on()] or [sqlite
2b960 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b970 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2b980 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72      then the arr
2b990 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  ay of [sqlite3_v
2b9a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61  alue] objects pa
2b9b0 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20  ssed as the.**  
2b9c0 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61          third pa
2b9d0 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61  rameter are alwa
2b9e0 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ys [protected sq
2b9f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ba00 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ects..*/.int sql
2ba10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ba20 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2ba30 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2ba40 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2ba50 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2ba60 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2ba70 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2ba80 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2ba90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2baa0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2bab0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2bac0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2bad0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2bae0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2baf0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2bb00 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2bb10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2bb20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2bb30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2bb40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2bb50 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2bb60 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2bb70 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2bb80 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2bb90 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2bba0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2bbb0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2bbc0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2bbd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2bbe0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2bbf0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2bc00 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2bc10 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
2bc20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2bc30 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 37  ncodings {F10267
2bc40 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
2bc50 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
2bc60 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
2bc70 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
2bc80 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
2bc90 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
2bca0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
2bcb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bcc0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
2bcd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bce0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
2bcf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bd00 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
2bd10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bd20 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
2bd30 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
2bd40 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
2bd50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
2bd60 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
2bd70 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2bd80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
2bd90 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
2bda0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2bdb0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
2bdc0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2bdd0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
2bde0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2bdf0 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73  solete Functions
2be00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2be10 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e  ctions are all n
2be20 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e  ow obsolete.  In
2be30 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2be40 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2be50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2be60 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77  th older code, w
2be70 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75  e continue to su
2be80 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66  pport.** these f
2be90 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76  unctions.  Howev
2bea0 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d  er, new developm
2beb0 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f  ent projects sho
2bec0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2bed0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2bee0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2bef0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2bf00 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2bf10 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2bf20 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2bf30 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2bf40 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e  ou want they do.
2bf50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bf60 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2bf70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2bf80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
2bf90 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2bfa0 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tmt*);.int sqlit
2bfb0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2bfc0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2bfd0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2bfe0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2bff0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
2c000 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  oid);.void sqlit
2c010 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
2c020 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  p(void);.int sql
2c030 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
2c040 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
2c050 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
2c060 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
2c070 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _int64);../*.** 
2c080 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2c090 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
2c0a0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
2c0b0 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a  s {F15100}.**.**
2c0c0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
2c0d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2c0e0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
2c0f0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
2c100 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
2c110 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
2c120 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
2c130 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
2c140 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
2c150 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2c160 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
2c170 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
2c180 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
2c190 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
2c1a0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
2c1b0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2c1c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c1d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c1e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c1f0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
2c200 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
2c210 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2c220 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2c230 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
2c240 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2c250 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
2c260 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
2c270 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
2c280 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2c290 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c2a0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
2c2b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c2c0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
2c2d0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
2c2e0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
2c2f0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
2c300 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
2c310 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
2c320 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
2c330 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c340 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
2c350 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
2c360 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
2c370 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c380 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
2c390 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
2c3a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c3b0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
2c3c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c3d0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
2c3e0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
2c3f0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2c400 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c410 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
2c420 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2c430 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2c440 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
2c450 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
2c460 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
2c470 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
2c480 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c490 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
2c4a0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2c4c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
2c4d0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
2c4e0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  umber..**.** The
2c4f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2c500 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2c510 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2c520 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2c530 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2c540 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2c550 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
2c560 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2c570 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2c580 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2c590 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2c5a0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2c5b0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2c5c0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2c5d0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2c5e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2c5f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2c600 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2c610 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2c620 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2c630 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2c640 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2c650 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2c660 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2c670 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2c680 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2c690 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2c6a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2c6b0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2c6c0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2c6d0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2c6e0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2c6f0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2c700 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2c710 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2c720 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2c730 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2c740 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2c750 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2c760 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2c770 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2c780 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2c790 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2c7a0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2c7b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2c7c0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2c7d0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2c7e0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2c7f0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2c800 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2c810 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2c820 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2c830 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2c840 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2c850 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2c860 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2c870 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2c880 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2c890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2c8a0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2c8b0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2c8c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2c8d0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2c8e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c8f0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2c900 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c910 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2c920 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2c930 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2c940 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2c950 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2c960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2c970 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
2c980 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2c990 2a 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b  * {F15103} The [
2c9a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2c9b0 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  ob(V)] interface
2c9c0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c9d0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2c9e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c9f0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2ca00 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65  o a BLOB and the
2ca10 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  n.**          re
2ca20 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ca30 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
2ca40 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
2ca50 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  15106} The [sqli
2ca60 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2ca70 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2ca80 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2ca90 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2caa0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
2cab0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
2cac0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2cad0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2cae0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2caf0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2cb00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2cb10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2cb20 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2cb30 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
2cb40 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20  _blob(V)] or.** 
2cb50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2cb60 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2cb70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d  ..**.** {F15109}
2cb80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2cb90 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20  lue_bytes16(V)] 
2cba0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2cbb0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2cbc0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2cbd0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2cbe0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2cbf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2cc00 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2cc10 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2cc20 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2cc30 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2cc40 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2cc50 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2cc60 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c  alue_text16(V)],
2cc70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2cc80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2cc90 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71  16be(V)], or [sq
2cca0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2ccb0 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16le(V)]..**.** 
2ccc0 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71  {F15112} The [sq
2ccd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2cce0 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2ccf0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2cd00 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2cd10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2cd20 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2cd30 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2cd40 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2cd50 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2cd60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2cd70 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
2cd80 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  5115} The [sqlit
2cd90 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d  e3_value_int(V)]
2cda0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2cdb0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2cdc0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2cdd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cde0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
2cdf0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2ce00 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2ce10 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2ce20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2ce30 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2ce40 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68  *.** {F15118} Th
2ce50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ce60 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72  _int64(V)] inter
2ce70 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2ce80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2ce90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2cea0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2ceb0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
2cec0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2ced0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2cee0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2cef0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2cf00 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65  .** {F15121} The
2cf10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cf20 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61  text(V)] interfa
2cf30 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2cf40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2cf50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cf60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2cf70 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2cf80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20  nated UTF-8.**  
2cf90 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2cfa0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2cfb0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2cfc0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
2cfd0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2cfe0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29  _value_text16(V)
2cff0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2d000 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2d010 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2d020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d030 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2d040 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2d050 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2d060 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2d070 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2d080 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
2d090 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2d0a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2d0b0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2d0c0 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b  * {F15127} The [
2d0d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d0e0 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
2d0f0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d100 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d110 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d120 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d130 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2d140 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2d150 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2d160 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
2d170 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2d180 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2d190 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2d1a0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2d1b0 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65  .** {F15130} The
2d1c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d1d0 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
2d1e0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2d1f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d200 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d210 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d220 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2d230 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2d240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2d250 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74  gned UTF-16 litt
2d260 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
2d270 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2d280 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d290 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2d2a0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33  g..**.** {F15133
2d2b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d2c0 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e  alue_type(V)] in
2d2d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2d2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2d2f0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2d300 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2d310 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2d320 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2d330 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2d340 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2d350 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2d360 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2d370 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d380 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a  e] object V..**.
2d390 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20  ** {F15136} The 
2d3a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e  [sqlite3_value_n
2d3b0 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20  umeric_type(V)] 
2d3c0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2d3d0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ts.**          t
2d3e0 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  he [protected sq
2d3f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d400 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65  ect V into eithe
2d410 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a  r an integer or.
2d420 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c  **          a fl
2d430 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2d440 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20  ue if it can do 
2d450 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  so without loss 
2d460 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  of.**          i
2d470 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20  nformation, and 
2d480 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b  returns one of [
2d490 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a  SQLITE_NULL],.**
2d4a0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2d4b0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2d4c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2d4d0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a  ITE_TEXT], or.**
2d4e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2d4f0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2d500 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a  priate for the.*
2d510 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2d520 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d530 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66  lue] object V af
2d540 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ter the conversi
2d550 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63  on attempt..*/.c
2d560 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d570 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2d580 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2d590 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2d5a0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2d5b0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2d5c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2d5d0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2d5e0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2d5f0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2d600 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d610 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2d620 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2d630 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2d640 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2d650 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2d660 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2d670 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2d680 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d690 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2d6a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2d6b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d6c0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2d6d0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2d6e0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2d6f0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2d700 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2d710 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2d720 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2d730 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2d740 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d750 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2d760 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2d770 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2d780 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2d790 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2d7a0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2d7b0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2d7c0 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d  Context {F16210}
2d7d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
2d7e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
2d7f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2d800 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
2d810 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2d820 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
2d830 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2d840 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2d850 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2d860 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2d870 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72  gate_context() r
2d880 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
2d890 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63   for a.** partic
2d8a0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20  ular aggregate, 
2d8b0 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73  SQLite allocates
2d8c0 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72   nBytes of memor
2d8d0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
2d8e0 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e  at.** memory, an
2d8f0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2d900 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65  ter to it. On se
2d910 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2d920 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
2d930 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2d940 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
2d950 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2d960 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65  te function inde
2d970 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  x,.** the same b
2d980 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
2d990 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  d. The implement
2d9a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67  ation of the agg
2d9b0 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a  regate can use.*
2d9c0 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  * the returned b
2d9d0 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
2d9e0 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
2d9f0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2da00 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
2da10 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
2da20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
2da30 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
2da40 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
2da50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2da60 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70   should be a cop
2da70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
2da80 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2da90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2daa0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2dab0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2dac0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
2dad0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2dae0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2daf0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2db00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
2db10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2db20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2db30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2db40 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
2db50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2db60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2db70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2db80 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54  **.** {F16211} T
2db90 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
2dba0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
2dbb0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2dbc0 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20  t(C,N)] for.**  
2dbd0 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63          a partic
2dbe0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66  ular instance of
2dbf0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75   an aggregate fu
2dc00 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61  nction (for a pa
2dc10 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20  rticular.**     
2dc20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20       context C) 
2dc30 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2dc40 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65   allocate N byte
2dc50 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  s of memory,.** 
2dc60 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68           zero th
2dc70 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
2dc80 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
2dc90 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  to the allocated
2dca0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
2dcb0 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d  F16213} If a mem
2dcc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2dcd0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2dce0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
2dcf0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2dd00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2dd10 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
2dd20 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a  n returns 0..**.
2dd30 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f  ** {F16215} Seco
2dd40 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2dd50 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  t invocations of
2dd60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2dd70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2dd80 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
2dd90 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65  r the same conte
2dda0 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20  xt pointer C.** 
2ddb0 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20           ignore 
2ddc0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
2ddd0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
2dde0 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65  nter to the same
2ddf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f  .**          blo
2de00 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74  ck of memory ret
2de10 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72  urned by the fir
2de20 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  st invocation..*
2de30 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68  *.** {F16217} Th
2de40 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2de50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61  ed by [sqlite3_a
2de60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2de70 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20  (C,N)] is.**    
2de80 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61        automatica
2de90 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65  lly freed on the
2dea0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73   next call to [s
2deb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2dec0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2ded0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2dee0 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ()] for the [pre
2def0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2df00 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
2df10 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72          the aggr
2df20 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61  egate function a
2df30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
2df40 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69  ontext C..*/.voi
2df50 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2df60 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2df70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2df80 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2df90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2dfa0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2dfb0 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a  ions {F16240}.**
2dfc0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2dfd0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2dfe0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2dff0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2e000 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2e010 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2e020 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2e030 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2e040 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2e050 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2e060 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2e070 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e080 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2e090 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2e0a0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2e0b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2e0c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
2e0d0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
2e0e0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2e0f0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2e100 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2e110 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
2e120 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e130 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2e140 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2e150 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2e160 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69  16243} The [sqli
2e170 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29  te3_user_data(C)
2e180 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2e190 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2e1a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20  e.**          P 
2e1b0 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65  pointer from the
2e1c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e1d0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2e1e0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
2e1f0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2e200 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e210 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ion16(D,X,N,E,P,
2e220 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61  F,S,L)] call tha
2e230 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  t.**          re
2e240 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c  gistered the SQL
2e250 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
2e260 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  ated with [sqlit
2e270 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
2e280 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2e290 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
2e2a0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2e2b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2e2c0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2e2d0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
2e2e0 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16250}.**.** T
2e2f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
2e300 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
2e310 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e320 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2e330 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
2e340 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e350 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
2e360 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2e370 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2e380 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2e390 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2e3a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e3b0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2e3c0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2e3d0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2e3e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2e3f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2e400 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2e410 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20  .**.** {F16253} 
2e420 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
2e430 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43  text_db_handle(C
2e440 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2e450 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2e460 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  he.**          D
2e470 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2e480 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2e490 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2e4a0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2e4b0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2e4c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e4d0 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2e4e0 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2e4f0 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2e500 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2e510 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2e520 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
2e530 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
2e540 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2e550 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2e560 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2e570 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2e580 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2e590 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2e5a0 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a  a {F16270}.**.**
2e5b0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2e5c0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2e5d0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2e5e0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2e5f0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2e600 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2e610 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2e620 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2e630 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2e640 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2e650 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e660 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2e670 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2e680 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2e690 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2e6a0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2e6b0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2e6c0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2e6d0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2e6e0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2e6f0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2e700 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2e710 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2e720 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2e730 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2e740 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2e750 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2e760 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2e770 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2e780 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2e790 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2e7a0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2e7b0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2e7c0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2e7d0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2e7e0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2e7f0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2e800 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2e810 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2e820 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2e830 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2e840 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2e850 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2e860 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2e870 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2e880 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2e890 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2e8a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e8b0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2e8c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2e8d0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2e8e0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2e8f0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2e900 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2e910 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2e920 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e930 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d  unction. If no m
2e940 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
2e950 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
2e960 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
2e970 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
2e980 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
2e990 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
2e9a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
2e9b0 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
2e9c0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
2e9d0 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
2e9e0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
2e9f0 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
2ea00 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2ea10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
2ea20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2ea30 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2ea40 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
2ea50 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
2ea60 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
2ea70 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
2ea80 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
2ea90 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
2eaa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2eab0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2eac0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
2ead0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2eae0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2eaf0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
2eb00 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
2eb10 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
2eb20 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20  estroyed..** If 
2eb30 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
2eb40 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2eb50 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2eb60 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69  r.** function gi
2eb70 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
2eb80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2eb90 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2eba0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
2ebb0 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f  data when the co
2ebc0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
2ebd0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
2ebe0 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65  hanges.** or whe
2ebf0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
2ec00 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77  ent completes, w
2ec10 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
2ec20 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  irst..**.** SQLi
2ec30 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61  te is free to ca
2ec40 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ll the destructo
2ec50 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64  r and drop metad
2ec60 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61  ata on any.** pa
2ec70 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
2ec80 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
2ec90 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
2eca0 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
2ecb0 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
2ecc0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2ecd0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2ece0 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
2ecf0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74  ..**.** In pract
2ed00 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
2ed10 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
2ed20 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
2ed30 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
2ed40 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
2ed50 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
2ed60 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
2ed70 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
2ed80 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20   values and SQL 
2ed90 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  variables..**.**
2eda0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2edb0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2edc0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2edd0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2ede0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2edf0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2ee00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2ee10 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20 54 68  *.** {F16272} Th
2ee20 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  e [sqlite3_get_a
2ee30 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74  uxdata(C,N)] int
2ee40 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2ee50 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
2ee60 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61       to metadata
2ee70 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ee80 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
2ee90 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
2eea0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2eeb0 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74     whose context
2eec0 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69   is C, or NULL i
2eed0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
2eee0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2eef0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
2ef00 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  th that paramete
2ef10 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34  r..**.** {F16274
2ef20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
2ef30 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2ef40 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  ,D)] interface a
2ef50 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74  ssigns a metadat
2ef60 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
2ef70 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e  inter P to the N
2ef80 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
2ef90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2efa0 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e   with context C.
2efb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20  .**.** {F16276} 
2efc0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2efd0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2efe0 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
2eff0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  e argument.**   
2f000 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20         which is 
2f010 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69  the metadata poi
2f020 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67  nter P following
2f030 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
2f040 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f050 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2f060 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74  P,D)] when SQLit
2f070 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
2f080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2f090 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a   metadata..**.**
2f0a0 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65   {F16277} SQLite
2f0b0 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20   ceases to hold 
2f0c0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20  metadata for an 
2f0d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  SQL function par
2f0e0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
2f0f0 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75     when the valu
2f100 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65  e of that parame
2f110 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  ter changes..**.
2f120 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e  ** {F16278} When
2f130 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2f140 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2f150 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2f160 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20  destructor.**   
2f170 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64         is called
2f180 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d   for any prior m
2f190 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2f1a0 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
2f1b0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2f1c0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20        context C 
2f1d0 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e  and parameter N.
2f1e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20  .**.** {F16279} 
2f1f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c  SQLite will call
2f200 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72   destructors for
2f210 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74   any metadata it
2f220 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20   is holding.**  
2f230 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72          in a par
2f240 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65  ticular [prepare
2f250 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77  d statement] S w
2f260 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  hen either.**   
2f270 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f280 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71  reset(S)] or [sq
2f290 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2f2a0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f  )] is called..*/
2f2b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2f2c0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2f2d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2f2e0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2f2f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2f300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2f310 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2f320 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2f330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f340 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2f350 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2f360 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2f370 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F10280}.**.** 
2f380 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
2f390 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
2f3a0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
2f3b0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
2f3c0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
2f3d0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
2f3e0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2f3f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
2f400 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63    If the destruc
2f410 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
2f420 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
2f430 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
2f440 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
2f450 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
2f460 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
2f470 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
2f480 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2f490 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68  e destroyed.  Th
2f4a0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
2f4b0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2f4c0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2f4d0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2f4e0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2f4f0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2f500 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2f510 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2f520 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2f530 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2f540 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2f550 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2f560 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2f570 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2f580 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2f590 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2f5a0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2f5b0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2f5c0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2f5d0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2f5e0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2f5f0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2f600 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2f610 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2f620 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2f630 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2f640 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2f650 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2f660 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2f670 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2f680 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2f690 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a  on {F16400}.**.*
2f6a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2f6b0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
2f6c0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
2f6d0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
2f6e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
2f6f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2f700 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
2f710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2f720 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2f730 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f740 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f750 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
2f760 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2f770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2f780 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2f790 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
2f7a0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2f7b0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
2f7c0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
2f7d0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
2f7e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2f7f0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
2f800 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
2f810 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
2f820 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
2f830 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2f840 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2f850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2f860 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2f870 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f880 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2f890 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2f8a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f8b0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2f8c0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2f8d0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2f8e0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2f8f0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2f900 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2f910 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2f920 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2f930 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
2f940 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f950 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
2f960 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
2f970 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2f980 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f990 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f9a0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
2f9b0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
2f9c0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
2f9d0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
2f9e0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
2f9f0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
2fa00 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
2fa10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2fa20 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
2fa30 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2fa40 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2fa50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fa60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fa70 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2fa80 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2fa90 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
2faa0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2fab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fac0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2fad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fae0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
2faf0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
2fb00 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
2fb10 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
2fb20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
2fb30 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2fb40 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
2fb50 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
2fb60 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
2fb70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fb80 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
2fb90 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2fba0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
2fbb0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
2fbc0 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74  age.  SQLite int
2fbd0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
2fbe0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
2fbf0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
2fc00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2fc10 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65  as UTF-8. SQLite
2fc20 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2fc30 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2fc40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2fc50 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
2fc60 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
2fc70 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74  yte order.  If t
2fc80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2fc90 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2fca0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2fcb0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fcc0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2fcd0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2fce0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
2fcf0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2fd00 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
2fd10 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2fd20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2fd30 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20  ** If the third 
2fd40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2fd50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fd60 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
2fd70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2fd80 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
2fd90 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2fda0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
2fdb0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
2fdc0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
2fdd0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2fde0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
2fdf0 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  sage..** The sql
2fe00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fe10 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
2fe20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2fe30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
2fe40 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
2fe50 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
2fe60 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
2fe70 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
2fe80 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
2fe90 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
2fea0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
2feb0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
2fec0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
2fed0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
2fee0 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  rm..** The sqlit
2fef0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2ff00 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2ff10 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2ff20 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2ff30 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2ff40 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2ff50 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2ff60 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  on.  By default,
2ff70 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
2ff80 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
2ff90 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e  OR.  A subsequen
2ffa0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call 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 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
2fff0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
30000 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ERROR..**.** The
30010 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30020 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
30030 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
30040 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
30050 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
30060 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
30070 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e  r BLOB is to lon
30080 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
30090 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
300a0 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
300b0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
300c0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
300d0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
300e0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
300f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
30100 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
30110 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30120 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
30130 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
30140 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
30150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30160 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30170 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
30180 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
30190 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
301a0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
301b0 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  nt..** The sqlit
301c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
301d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
301e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
301f0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
30200 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30210 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
30220 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
30230 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
30240 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
30250 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
30260 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30270 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
30280 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
30290 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
302a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
302b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
302c0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
302d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
302e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
302f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30300 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
30310 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30320 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
30330 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30340 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
30350 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
30360 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
30370 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30380 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30390 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
303a0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
303b0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
303c0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
303d0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
303e0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
303f0 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
30400 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
30410 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c  ectively..** SQL
30420 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
30430 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
30440 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
30450 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
30460 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
30470 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30480 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
30490 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
304a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
304b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
304c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
304d0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
304e0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
304f0 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
30500 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
30510 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
30520 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
30530 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
30540 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
30550 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
30560 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
30570 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
30580 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
30590 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
305a0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
305b0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
305c0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
305d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
305e0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
305f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30600 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
30610 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
30620 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
30630 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
30640 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
30650 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
30660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
30670 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
30680 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
30690 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
306a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
306b0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
306c0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
306d0 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
306e0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
306f0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
30700 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
30710 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
30720 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30730 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
30740 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  es or.** sqlite3
30750 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
30760 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
30770 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
30780 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
30790 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
307a0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
307b0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
307c0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
307d0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
307e0 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c  y the it or call
307f0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68   a destructor wh
30800 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
30810 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
30820 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
30830 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
30840 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
30850 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
30860 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
30870 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
30880 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
30890 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
308a0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
308b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
308c0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
308d0 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
308e0 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
308f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
30900 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
30910 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
30920 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30930 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
30940 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
30950 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
30960 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30970 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
30980 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
30990 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
309a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
309b0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
309c0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
309d0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
309e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
309f0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
30a00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
30a10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
30a20 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
30a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
30a40 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
30a50 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
30a60 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
30a70 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
30a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
30a90 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
30aa0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41  thout harm..** A
30ab0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30ac0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30ad0 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
30ae0 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
30af0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
30b00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30b10 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
30b20 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
30b30 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
30b40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
30b50 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
30b60 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
30b70 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
30b80 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
30b90 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
30ba0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
30bb0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
30bc0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
30bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30be0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
30bf0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
30c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
30c10 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
30c20 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
30c30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
30c40 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
30c50 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64 65   {F16403} The de
30c60 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c  fault return val
30c70 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20  ue from any SQL 
30c80 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c  function is NULL
30c90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d  ..**.** {F16406}
30ca0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30cb0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
30cc0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
30cd0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
30ce0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
30cf0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
30d00 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68   to be a BLOB th
30d10 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a  at is N bytes.**
30d20 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e            in len
30d30 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e  gth and with con
30d40 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20  tent pointed to 
30d50 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  by V..**.** {F16
30d60 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  409} The [sqlite
30d70 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
30d80 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
30d90 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30da0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30db0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30dc0 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f   C to be the flo
30dd0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
30de0 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
30df0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
30e00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c  _result_error(C,
30e10 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  V,N)] interface 
30e20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
30e30 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
30e40 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30e50 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
30e60 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
30e70 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
30e80 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
30e90 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72   and a UTF-8 err
30ea0 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65  or message copie
30eb0 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74  d from V up to t
30ec0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
30ed0 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f  irst zero byte o
30ee0 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20  r until N bytes 
30ef0 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73  are read if N is
30f00 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   positive..**.**
30f10 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b 73   {F16415} The [s
30f20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30f30 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e  ror16(C,V,N)] in
30f40 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30f50 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
30f60 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
30f70 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30f80 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
30f90 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
30fa0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
30fb0 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55  E_ERROR] and a U
30fc0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
30fd0 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65  e order error me
30fe0 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
30ff0 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20    copied from V 
31000 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
31010 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
31020 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
31030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
31040 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
31050 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
31060 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16418} The [sqli
31070 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31080 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65  _toobig(C)] inte
31090 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
310a0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
310b0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
310c0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
310d0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
310e0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
310f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
31100 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20  ITE_TOOBIG] and 
31110 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
31120 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
31130 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65  .** {F16421} The
31140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31150 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d  _error_nomem(C)]
31160 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31170 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
31180 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
31190 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
311a0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
311b0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
311c0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
311d0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
311e0 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
311f0 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
31200 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d  ..**.** {F16424}
31210 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31220 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
31230 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,E)] interface 
31240 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
31250 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
31260 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
31270 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
31280 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
31290 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20  rror code E..** 
312a0 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72           The err
312b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
312c0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
312d0 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68 65  .** {F16427} The
312e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
312f0 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72  _int(C,V)] inter
31300 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
31320 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
31330 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
31340 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  e 32-bit integer
31350 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
31360 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71  {F16430} The [sq
31370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
31380 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  64(C,V)] interfa
31390 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
313a0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
313b0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
313c0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
313d0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  64-bit integer v
313e0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
313f0 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  16433} The [sqli
31400 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
31410 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
31420 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
31430 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
31440 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
31450 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
31460 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65 20  ** {F16436} The 
31470 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31480 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  text(C,V,N,D)] i
31490 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
314a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
314b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
314c0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
314d0 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69  e the UTF-8 stri
314e0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56  ng.**          V
314f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
31500 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
31510 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
31520 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
31530 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
31540 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
31550 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39  e..**.** {F16439
31560 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31570 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
31580 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
31590 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
315a0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
315b0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
315c0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
315d0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
315e0 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
315f0 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
31600 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
31610 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
31620 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
31630 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
31640 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
31650 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
31660 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65  .** {F16442} The
31670 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31680 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
31690 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
316a0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
316b0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
316c0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
316d0 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31   to be the UTF-1
316e0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
316f0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
31700 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
31710 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
31720 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
31730 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
31740 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69 66   N bytes or V if
31750 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
31760 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
31770 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
31780 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
31790 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
317a0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
317b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
317c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
317d0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
317e0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
317f0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
31800 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
31810 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31820 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
31830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
31840 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
31850 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
31860 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
31870 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20  ** {F16448} The 
31880 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31890 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65  value(C,V)] inte
318a0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
318b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
318c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
318d0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
318e0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
318f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
31900 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
31910 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  t V..**.** {F164
31920 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
31930 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
31940 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,N)] interface
31950 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
31960 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
31970 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
31980 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62  n C to be an N-b
31990 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20  yte BLOB of all 
319a0 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  zeros..**.** {F1
319b0 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6454} The [sqlit
319c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
319d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
319e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
319f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
31a00 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20  terfaces make a 
31a10 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65 72  copy of their er
31a20 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
31a30 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20  ngs before.**   
31a40 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67         returning
31a50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d  ..**.** {F16457}
31a60 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75   If the D destru
31a70 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74  ctor parameter t
31a80 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
31a90 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
31aa0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
31ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31ac0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73  xt(C,V,N,D)], [s
31ad0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31ae0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  xt16(C,V,N,D)],.
31af0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
31b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31b10 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  16be(C,V,N,D)], 
31b20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
31b30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31b40 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
31b50 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e  ] is the constan
31b60 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  t [SQLITE_STATIC
31b70 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ].**          th
31b80 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72  en no destructor
31b90 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20   is ever called 
31ba0 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56  on the pointer V
31bb0 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20   and SQLite.**  
31bc0 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73 20          assumes 
31bd0 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61  that V is immuta
31be0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ble..**.** {F164
31bf0 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  60} If the D des
31c00 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
31c10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
31c20 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
31c30 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
31c40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31c50 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
31c60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31c70 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
31c80 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
31c90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31ca0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
31cb0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
31cc0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
31cd0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
31ce0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
31cf0 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  tant.**         
31d00 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
31d10 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74  NT] then the int
31d20 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20  erfaces makes a 
31d30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
31d40 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20          content 
31d50 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73  of V and retains
31d60 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a   the copy..**.**
31d70 20 7b 46 31 36 34 36 33 7d 20 49 66 20 74 68 65   {F16463} If the
31d80 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
31d90 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31da0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31db0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
31dc0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
31dd0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
31de0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
31df0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
31e00 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
31e10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
31e20 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
31e30 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
31e40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
31e50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
31e60 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f  (C,V,N,D)] is so
31e70 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  me value other t
31e80 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
31e90 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
31ea0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e  QLITE_STATIC] an
31eb0 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  d [SQLITE_TRANSI
31ec0 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ENT] then.**    
31ed0 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c        SQLite wil
31ee0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
31ef0 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56  tructor D with V
31f00 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   as its only arg
31f10 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ument.**        
31f20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69    when it has fi
31f30 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
31f40 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64  V value..*/.void
31f50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31f60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
31f70 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
31f80 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
31f90 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
31fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
31fb0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
31fc0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
31fd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31fe0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
31ff0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32000 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
32010 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32020 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
32030 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32040 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
32050 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32060 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
32070 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32080 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
32090 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
320a0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
320b0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
320c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
320d0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
320e0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
320f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32100 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
32110 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
32120 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32130 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
32140 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
32150 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
32160 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
32170 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
32180 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
32190 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
321a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
321b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
321c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
321d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
321e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
321f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32200 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32210 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
32220 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
32230 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
32240 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32250 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32260 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
32270 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
32280 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
32290 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
322a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
322b0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
322c0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
322d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
322e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
322f0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
32300 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32310 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
32320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32330 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
32340 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
32350 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
32360 53 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30  Sequences {F1660
32370 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  0}.**.** These f
32380 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65  unctions are use
32390 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c  d to add new col
323a0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
323b0 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   to the.** [data
323c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
323d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
323e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
323f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
32400 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c   of the new coll
32410 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
32420 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61  s specified as a
32430 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
32440 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
32450 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
32460 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
32470 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32480 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
32490 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c  6 string for sql
324a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
324b0 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c  ation16(). In al
324c0 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
324d0 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
324e0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
324f0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
32500 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
32510 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f  rgument may be o
32520 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
32530 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  nts [SQLITE_UTF8
32540 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  ],.** [SQLITE_UT
32550 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54  F16LE] or [SQLIT
32560 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
32570 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
32580 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
32590 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
325a0 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
325b0 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
325c0 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
325d0 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
325e0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
325f0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
32600 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
32610 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
32620 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
32630 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
32640 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74  UTF16_ALIGNED] t
32650 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a  o indicate that.
32660 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
32670 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
32680 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
32690 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
326a0 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74  * of UTF-16 in t
326b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
326c0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
326d0 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a   computer..**.**
326e0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
326f0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
32700 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
32710 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
32720 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
32730 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c    If it is NULL,
32740 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
32750 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
32760 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
32770 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
32780 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
32790 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
327a0 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68  .** Each time th
327b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75  e application su
327c0 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
327d0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
327e0 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69  s passed.** as i
327f0 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
32800 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  er a copy of the
32810 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
32820 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
32830 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
32840 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32850 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
32860 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32870 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
32880 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
32890 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c  ents to the appl
328a0 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
328b0 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
328c0 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
328d0 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
328e0 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61   a (length, data
328f0 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ) pair and encod
32900 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
32910 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
32920 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
32930 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
32940 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
32950 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
32960 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d  egistered. {END}
32970 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
32980 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
32990 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
329a0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
329b0 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
329c0 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66  ositive if the f
329d0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
329e0 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75  ess than,.** equ
329f0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
32a00 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
32a10 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28  d string. i.e. (
32a20 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47  STRING1 - STRING
32a30 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  2)..**.** The sq
32a40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32a50 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
32a60 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
32a70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
32a80 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
32a90 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
32aa0 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
32ab0 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
32ac0 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
32ad0 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73  lation.  The des
32ae0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
32af0 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
32b00 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
32b10 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
32b20 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
32b30 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
32b40 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
32b50 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
32b60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32b70 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c  on_v2()..** Coll
32b80 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
32b90 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  oyed when they a
32ba0 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
32bb0 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20   later calls to 
32bc0 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e  the.** collation
32bd0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
32be0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ons or when the 
32bf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32c00 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a  tion] is closed.
32c10 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
32c20 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
32c30 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32c40 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73  .** {F16603} A s
32c50 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
32c60 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
32c70 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
32c80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
32c90 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74  ,X,E,P,F,D)] int
32ca0 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
32cb0 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e     registers fun
32cc0 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63  ction F as the c
32cd0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
32ce0 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20  on used to.**   
32cf0 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
32d00 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20   collation X on 
32d10 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32d20 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a  nnection] B for.
32d30 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
32d40 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63  bases having enc
32d50 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b  oding E..**.** {
32d60 46 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75  F16604} SQLite u
32d70 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58  nderstands the X
32d80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
32d90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32da0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32db0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
32dc0 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74  ,D)] as a zero-t
32dd0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
32de0 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
32df0 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  ng in which case
32e00 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20   is ignored for 
32e10 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73  ASCII characters
32e20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
32e30 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20   is significant 
32e40 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68  for non-ASCII ch
32e50 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
32e60 7b 46 31 36 36 30 36 7d 20 53 75 63 63 65 73 73  {F16606} Success
32e70 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ive calls to [sq
32e80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32e90 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
32ea0 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
32eb0 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d      with the sam
32ec0 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20  e values for B, 
32ed0 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69  X, and E, overri
32ee0 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a  de prior values.
32ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50  **          of P
32f00 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a  , F, and D..**.*
32f10 2a 20 7b 46 31 36 36 30 39 7d 20 49 66 20 74 68  * {F16609} If th
32f20 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69  e destructor D i
32f30 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
32f40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
32f50 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
32f60 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20           is not 
32f70 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20  NULL then it is 
32f80 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75  called with argu
32f90 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a  ment P when the.
32fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
32fb0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
32fc0 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c  s dropped by SQL
32fd0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  ite..**.** {F166
32fe0 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  12} A collating 
32ff0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
33000 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f  ped when it is o
33010 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a  verloaded..**.**
33020 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c   {F16615} A coll
33030 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
33040 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74  s dropped when t
33050 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
33060 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
33070 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69     is closed usi
33080 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
33090 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  e()]..**.** {F16
330a0 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72  618} The pointer
330b0 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   P in [sqlite3_c
330c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
330d0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
330e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
330f0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
33100 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
33110 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d  meter to the com
33120 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20  parison.**      
33130 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66      function F f
33140 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  or all subsequen
33150 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  t invocations of
33160 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32   F..**.** {F1662
33170 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  1} A call to [sq
33180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33190 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
331a0 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a  )] is exactly.**
331b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
331c0 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20  me as a call to 
331d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
331e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20  collation_v2()] 
331f0 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
33200 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65   the same parame
33210 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20  ters and a NULL 
33220 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a  destructor..**.*
33230 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c 6f  * {F16624} Follo
33240 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f  wing a [sqlite3_
33250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33260 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
33270 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ],.**          S
33280 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63  QLite uses the c
33290 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
332a0 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78  on F for all tex
332b0 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20  t comparison.** 
332c0 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69           operati
332d0 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  ons on the [data
332e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
332f0 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65   B on text value
33300 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  s that.**       
33310 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61     use the colla
33320 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61  ting sequence na
33330 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  med X..**.** {F1
33340 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6627} The [sqlit
33350 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33360 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29  ion16(B,X,E,P,F)
33370 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  ] works the same
33380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
33390 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
333a0 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c  collation(B,X,E,
333b0 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61  P,F)] except tha
333c0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
333d0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65    collation name
333e0 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64   X is understood
333f0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
33400 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
33410 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74  **          inst
33420 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
33430 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65  .** {F16630} Whe
33440 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61  n multiple compa
33450 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  rison functions 
33460 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f  are available fo
33470 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  r the same.**   
33480 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
33490 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74   sequence, SQLit
334a0 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e  e chooses the on
334b0 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63  e whose text enc
334c0 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  oding.**        
334d0 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c    requires the l
334e0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63  east amount of c
334f0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74  onversion from t
33500 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  he default.**   
33510 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f         text enco
33520 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ding of the data
33530 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  base..*/.int sql
33540 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33550 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
33560 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
33570 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
33580 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
33590 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
335a0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
335b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
335c0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
335d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
335e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
335f0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
33600 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
33610 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
33620 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
33630 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
33640 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33650 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33660 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
33670 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33680 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
33690 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
336a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
336b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
336c0 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
336d0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
336e0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
336f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33700 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33710 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
33720 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
33730 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
33740 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a  acks {F16700}.**
33750 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
33760 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
33770 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
33780 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
33790 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
337a0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
337b0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
337c0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
337d0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
337e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
337f0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63  nection] to be c
33800 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
33810 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
33820 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
33830 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
33840 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
33850 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
33860 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
33870 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33880 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
33890 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
338a0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
338b0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
338c0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
338d0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
338e0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31  ed in UTF-8. {F1
338f0 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
33900 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33910 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
33920 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
33930 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
33940 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
33950 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
33960 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  * A call to eith
33970 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
33980 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
33990 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
339a0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
339b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
339c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
339d0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
339e0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
339f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
33a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33a10 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
33a20 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
33a30 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
33a40 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
33a50 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
33a60 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
33a70 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
33a80 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
33a90 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
33aa0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
33ab0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
33ac0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
33ad0 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
33ae0 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
33af0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
33b00 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
33b10 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
33b20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
33b30 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
33b40 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
33b50 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
33b60 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
33b70 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
33b80 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
33b90 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
33ba0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
33bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
33bc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
33bd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33be0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
33bf0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
33c00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33c10 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
33c20 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
33c30 46 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73  F16702} A succes
33c40 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
33c50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33c60 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a  needed(D,P,F)].*
33c70 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
33c80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33c90 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29  _needed16(D,P,F)
33ca0 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20  ] causes.**     
33cb0 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
33cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
33cd0 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62   to invoke callb
33ce0 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74  ack F with first
33cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
33d00 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
33d10 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d  r it needs a com
33d20 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
33d30 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20   for a.**       
33d40 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
33d50 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f  uence that it do
33d60 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75  es not know abou
33d70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34  t..**.** {F16704
33d80 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75  } Each successfu
33d90 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33da0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33db0 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ded()] or.**    
33dc0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
33dd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33de0 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  6()] overrides t
33df0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69  he callback regi
33e00 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
33e10 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
33e20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33e30 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61  ion] by prior ca
33e40 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  lls to either.**
33e50 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
33e60 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  ace..**.** {F167
33e70 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  06} The name of 
33e80 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f  the requested co
33e90 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33ea0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a   passed in the.*
33eb0 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70  *          4th p
33ec0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33ed0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55  callback is in U
33ee0 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c  TF-8 if the call
33ef0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
33f00 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20   was registered 
33f10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
33f20 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
33f30 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
33f40 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20     is in UTF-16 
33f50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33f60 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r if the callbac
33f70 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  k was.**        
33f80 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69    registered usi
33f90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
33fa0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33fb0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
33fc0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33fd0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
33fe0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
33ff0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34000 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34010 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
34020 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
34030 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
34040 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34050 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
34060 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
34070 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
34080 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
34090 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
340a0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
340b0 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
340c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
340d0 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
340e0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
340f0 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
34100 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
34110 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
34120 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
34130 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
34140 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
34150 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
34160 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
34170 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
34180 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
34190 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
341a0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
341b0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
341c0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
341d0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
341e0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
341f0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
34200 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
34210 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
34220 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
34230 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
34240 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
34250 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
34260 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
34270 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
34280 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
34290 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
342a0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
342b0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
342c0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
342d0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
342e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
342f0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
34300 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34310 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34320 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
34330 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
34340 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
34350 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
34360 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
34370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
34380 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
34390 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
343a0 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10530}.**.** T
343b0 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
343c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
343d0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
343e0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
343f0 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
34400 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
34410 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
34420 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
34430 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
34440 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
34450 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
34460 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
34470 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
34480 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
34490 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
344a0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
344b0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
344c0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
344d0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
344e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
344f0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
34500 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
34510 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
34520 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
34530 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
34540 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
34550 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
34560 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
34570 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
34580 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
34590 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
345a0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  vfs] object..**.
345b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
345c0 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68  *.** {F10533} Th
345d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  e [sqlite3_sleep
345e0 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  (M)] interface i
345f0 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65  nvokes the xSlee
34600 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  p.**          me
34610 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
34620 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
34630 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  |VFS] in order t
34640 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75  o.**          su
34650 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20  spend execution 
34660 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  of the current t
34670 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61  hread for at lea
34680 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  st.**          M
34690 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
346a0 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68  *.** {F10536} Th
346b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  e [sqlite3_sleep
346c0 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (M)] interface r
346d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
346e0 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
346f0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
34700 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
34710 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65  requested of the
34720 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20   operating.**   
34730 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77         system, w
34740 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61  hich might be la
34750 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61  rger than the pa
34760 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e  rameter M..*/.in
34770 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
34780 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
34790 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
347a0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
347b0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
347c0 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a  s {F10310}.**.**
347d0 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
347e0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
347f0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
34800 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
34810 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
34820 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
34830 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
34840 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
34850 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
34860 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  y SQLite will be
34870 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
34880 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74  directory.  If t
34890 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
348a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
348b0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
348c0 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
348d0 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
348e0 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
348f0 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
34900 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
34910 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20   safe to modify 
34920 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e  this variable on
34930 63 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  ce a [database c
34940 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61  onnection].** ha
34950 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20  s been opened.  
34960 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
34970 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
34980 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
34990 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
349a0 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
349b0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
349c0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
349d0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
349e0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e  ave been call an
349f0 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  d remain unchang
34a00 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ed thereafter..*
34a10 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
34a20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
34a30 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
34a40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
34a50 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
34a60 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49 6e  e Database Is In
34a70 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
34a80 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 20 4b 45  e {F12930}.** KE
34a90 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
34aa0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
34ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
34ac0 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
34ad0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
34ae0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
34af0 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
34b00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34b10 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
34b20 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
34b30 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
34b40 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  vely.  Autocommi
34b50 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
34b60 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f  default..** Auto
34b70 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
34b80 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
34b90 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
34ba0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
34bb0 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
34bc0 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
34bd0 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
34be0 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
34bf0 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
34c00 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
34c10 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
34c20 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
34c30 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72  transaction (err
34c40 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
34c50 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
34c60 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20  LITE_IOERR],.** 
34c70 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
34c80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
34c90 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
34ca0 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
34cb0 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
34cc0 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
34cd0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
34ce0 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
34cf0 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
34d00 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61  whether SQLite a
34d10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
34d20 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
34d30 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
34d40 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
34d50 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
34d60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
34d70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
34d80 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  931} The [sqlite
34d90 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
34da0 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (D)] interface r
34db0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
34dc0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  or.**          z
34dd0 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61  ero if the [data
34de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34df0 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20   D is or is not 
34e00 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a  in autocommit.**
34e10 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20            mode, 
34e20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
34e30 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75 74  .** {F12932} Aut
34e40 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
34e50 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
34e60 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41 75  *.** {F12933} Au
34e70 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
34e80 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 73   disabled by a s
34e90 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e  uccessful [BEGIN
34ea0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  ] statement..**.
34eb0 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f  ** {F12934} Auto
34ec0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65  commit mode is e
34ed0 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  nabled by a succ
34ee0 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20  essful [COMMIT] 
34ef0 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a  or [ROLLBACK].**
34f00 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
34f10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ent..**.** LIMIT
34f20 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  ATIONS:.**.** {A
34f30 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65  12936} If anothe
34f40 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
34f50 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
34f60 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
34f70 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20  tabase.**       
34f80 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68     connection wh
34f90 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
34fa0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
34fb0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
34fc0 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ue.**          i
34fd0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
34fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
34ff0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
35000 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
35010 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
35020 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
35030 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
35040 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d  atement {F13120}
35050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35060 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
35070 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
35080 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35090 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
350a0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
350b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
350c0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65  t] belongs.  The
350d0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
350e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
350f0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
35100 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61  e is the same da
35110 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68  tabase handle th
35120 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
35130 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
35140 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
35150 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
35160 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
35170 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
35180 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
35190 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
351a0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
351b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
351c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20  .**.** {F13123} 
351d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
351e0 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72  handle(S)] inter
351f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
35200 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
35210 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62     to the [datab
35220 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35230 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
35240 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
35250 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35260 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74  ent] S..*/.sqlit
35270 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
35280 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
35290 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
352a0 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
352b0 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
352c0 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 34 30 7d  atement {F13140}
352d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
352e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
352f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
35300 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
35310 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
35320 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
35330 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
35340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35350 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74  ] pDb.  If pStmt
35360 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
35370 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
35380 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
35390 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
353a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
353b0 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
353c0 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
353d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
353e0 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65  .  If no prepare
353f0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
35400 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
35410 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
35420 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
35430 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
35440 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
35450 2a 20 7b 46 31 33 31 34 33 7d 20 49 66 20 44 20  * {F13143} If D 
35460 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
35470 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
35480 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  holds one or mor
35490 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e  e.**          un
354a0 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61  finalized [prepa
354b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
354c0 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  and S is a NULL 
354d0 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20  pointer,.**     
354e0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
354f0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
35500 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  S)] routine shal
35510 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  l return a point
35520 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
35530 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65  o one of the pre
35540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
35550 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
35560 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34   D..**.** {F1314
35570 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61  6} If D is a [da
35580 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35590 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f  n] that holds no
355a0 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20   unfinalized.** 
355b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
355c0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61  ed statements] a
355d0 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  nd S is a NULL p
355e0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ointer, then.** 
355f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35600 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
35610 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
35620 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
35630 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
35640 31 33 31 34 39 7d 20 49 66 20 53 20 69 73 20 61  13149} If S is a
35650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35660 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61  ment] in the [da
35670 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35680 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
35690 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68   and S is not th
356a0 65 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  e last prepared 
356b0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20  statement in D, 
356c0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
356d0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
356e0 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
356f0 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
35700 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
35710 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78        to the nex
35720 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
35730 6d 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20  ment in D after 
35740 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 35 32  S..**.** {F13152
35750 7d 20 49 66 20 53 20 69 73 20 74 68 65 20 6c 61  } If S is the la
35760 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
35770 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a  tement] in the.*
35780 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
35790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
357a0 20 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c   D then the [sql
357b0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
357c0 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  , S)].**        
357d0 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20    routine shall 
357e0 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
357f0 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
35800 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
35810 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
35820 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
35830 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
35840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
35850 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
35860 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
35870 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 35  Callbacks {F1295
35880 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
35890 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
358a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
358b0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
358c0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
358d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
358e0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
358f0 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
35900 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
35910 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
35920 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
35930 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
35940 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
35950 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35960 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
35970 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  en..** The sqlit
35980 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
35990 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
359a0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
359b0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
359c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
359d0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
359e0 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
359f0 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
35a00 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
35a10 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
35a20 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
35a30 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
35a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35a50 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
35a60 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20  en..** The pArg 
35a70 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
35a80 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
35a90 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49  e callback..** I
35aa0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
35ab0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
35ac0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
35ad0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
35ae0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
35af0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
35b00 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
35b10 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
35b20 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
35b30 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
35b40 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c   its.** pArg val
35b50 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
35b60 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
35b70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
35b80 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61  ** Registering a
35b90 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
35ba0 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
35bb0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  back..**.** For 
35bc0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
35bd0 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
35be0 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
35bf0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
35c00 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
35c10 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
35c20 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
35c30 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
35c40 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
35c50 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
35c60 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
35c70 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
35c80 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
35c90 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
35ca0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
35cb0 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
35cc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
35cd0 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
35ce0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35cf0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
35d00 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ed..** The rollb
35d10 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
35d20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
35d30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
35d40 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
35d50 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
35d60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
35d70 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
35d80 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
35d90 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  his </todo>.**.*
35da0 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65  * These are expe
35db0 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
35dc0 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a  ces and are subj
35dd0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
35de0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
35df0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20  .**.** {F12951} 
35e00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  The [sqlite3_com
35e10 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
35e20 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
35e30 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
35e40 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
35e50 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
35e60 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
35e70 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
35e80 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
35e90 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
35ea0 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s on the [databa
35eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
35ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d  ..**.** {F12952}
35ed0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
35ee0 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
35ef0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
35f00 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
35f10 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  nt.**          f
35f20 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
35f30 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
35f40 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
35f50 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20  nnection] D,.** 
35f60 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
35f70 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
35f80 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ll for a particu
35f90 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  lar database con
35fa0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
35fb0 20 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20 63   {F12953} Each c
35fc0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35fd0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f  commit_hook()] o
35fe0 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61  verwrites the ca
35ff0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
36000 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79     registered by
36010 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a   prior calls..**
36020 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66 20  .** {F12954} If 
36030 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74  the F argument t
36040 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  o [sqlite3_commi
36050 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
36060 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
36070 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d     then the comm
36080 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
36090 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64   is canceled and
360a0 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
360b0 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
360c0 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
360d0 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a  action commits..
360e0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49  **.** {F12955} I
360f0 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c  f the commit cal
36100 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
36110 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  n-zero then the 
36120 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20  commit is.**    
36130 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20        converted 
36140 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
36150 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20  .**.** {F12961} 
36160 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  The [sqlite3_rol
36170 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
36180 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
36190 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
361a0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
361b0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
361c0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
361d0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
361e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
361f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
36200 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64  s back on the [d
36210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36220 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
36230 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
36240 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36250 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
36260 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
36270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
36280 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
36290 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
362a0 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  h the same.**   
362b0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
362c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
362d0 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
362e0 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  irst call.**    
362f0 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74        for a part
36300 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20  icular database 
36310 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
36320 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63  .** {F12963} Eac
36330 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
36340 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36350 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
36360 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
36370 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
36380 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
36390 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34  s..**.** {F12964
363a0 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
363b0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
363c0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
363d0 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
363e0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
363f0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
36400 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
36410 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
36420 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
36430 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
36440 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
36450 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76  rolls back..*/.v
36460 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
36470 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
36480 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
36490 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
364a0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
364b0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
364c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
364d0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
364e0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
364f0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
36500 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
36510 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2970}.**.** The 
36520 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36530 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
36540 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
36550 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
36560 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
36570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36580 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
36590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
365a0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
365b0 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
365c0 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
365d0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
365e0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
365f0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
36600 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
36610 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
36620 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
36630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36640 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
36650 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
36660 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
36670 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
36680 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
36690 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
366a0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
366b0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
366c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
366d0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
366e0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
366f0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
36700 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
36710 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
36720 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ** The second ca
36730 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
36740 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
36750 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
36760 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
36770 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
36780 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
36790 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
367a0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
367b0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
367c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20  invoked..** The 
367d0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
367e0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
367f0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
36800 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
36810 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** database a
36820 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  nd table name co
36830 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
36840 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68  ected row..** Th
36850 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
36860 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
36870 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
36880 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65 20  ow. In the case 
36890 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c  of.** an update,
368a0 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
368b0 69 64 20 61 66 74 65 72 20 74 68 65 20 75 70 64  id after the upd
368c0 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
368d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
368e0 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
368f0 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
36900 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
36910 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
36920 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
36930 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
36940 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
36950 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
36960 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
36970 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
36980 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a   its pArg value.
36990 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
369a0 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
369b0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
369c0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
369d0 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68  *.** {F12971} Th
369e0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
369f0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
36a00 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
36a10 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
36a20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
36a30 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
36a40 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72  d with first par
36a50 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
36a60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
36a70 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64  table row is mod
36a80 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c  ified, inserted,
36a90 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a   or deleted on.*
36aa0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
36ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36ac0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
36ad0 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  12973} The [sqli
36ae0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
36af0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
36b00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  e returns the va
36b10 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
36b20 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65  of P for the pre
36b30 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68  vious call on th
36b40 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
36b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a   connection] D,.
36b60 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
36b70 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73  ULL for the firs
36b80 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  t call..**.** {F
36b90 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70  12975} If the up
36ba0 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
36bb0 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33  ck F in [sqlite3
36bc0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
36bd0 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,P)].**         
36be0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
36bf0 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c  e no update call
36c00 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a  backs are made..
36c10 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45  **.** {F12977} E
36c20 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
36c30 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36c40 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64  (D,F,P)] overrid
36c50 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a  es prior calls.*
36c60 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
36c70 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65  e same interface
36c80 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
36c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36ca0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
36cb0 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20  979} The update 
36cc0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
36cd0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
36ce0 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
36cf0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61  m.**          ta
36d00 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c  bles such as sql
36d10 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
36d20 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61  qlite_sequence a
36d30 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  re modified..**.
36d40 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20  ** {F12981} The 
36d50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
36d60 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63   to the update c
36d70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
36d80 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53      is one of [S
36d90 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
36da0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f  SQLITE_DELETE] o
36db0 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
36dc0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  ],.**          d
36dd0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
36de0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
36df0 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
36e00 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ck to be invoked
36e10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d  ..**.** {F12983}
36e20 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
36e30 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
36e40 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
36e50 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
36e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
36e70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
36e80 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68  UTF-8 strings wh
36e90 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65  ich are the name
36ea0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  s of the.**     
36eb0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e       database an
36ec0 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20  d table that is 
36ed0 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a  being updated...
36ee0 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20  ** {F12985} The 
36ef0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
36f00 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
36f10 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77  rowid of the row
36f20 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20   after.**       
36f30 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63     the change oc
36f40 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  curs..*/.void *s
36f50 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
36f60 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
36f70 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
36f80 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
36f90 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
36fa0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
36fb0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
36fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
36fd0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
36fe0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
36ff0 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 20 4b 45  e {F10330}.** KE
37000 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
37010 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63  cache} {shared c
37020 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ache mode}.**.**
37030 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
37040 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
37050 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
37060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
37070 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
37080 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
37090 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
370a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
370b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
370c0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
370d0 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
370e0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
370f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
37100 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
37110 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
37120 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
37130 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
37140 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
37150 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
37160 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b  ntire process. {
37170 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20  END}.** This is 
37180 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
37190 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
371a0 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
371b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
371c0 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
371d0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
371e0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
371f0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
37200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
37210 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
37220 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
37230 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
37240 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
37250 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37260 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
37270 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
37280 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
37290 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
372a0 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
372b0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
372c0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
372d0 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
372e0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
372f0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
37300 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
37310 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
37320 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
37330 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
37340 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
37350 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
37360 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
37370 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
37380 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
37390 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
373a0 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
373b0 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
373c0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rror..**.** This
373d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
373e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
373f0 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
37400 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
37410 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
37420 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
37430 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
37440 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
37450 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
37460 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
37470 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
37480 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
37490 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
374a0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
374b0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
374c0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
374d0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
374e0 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
374f0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
37500 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
37510 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 31 7d  :.**.** {F10331}
37520 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
37530 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
37540 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
37550 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20  ed_cache(B)].** 
37560 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e           will en
37570 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
37580 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
37590 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71  e for any subseq
375a0 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  uently.**       
375b0 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61     created [data
375c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
375d0 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f   in the same pro
375e0 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  cess..**.** {F10
375f0 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64  336} When shared
37600 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
37610 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
37620 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
37630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
37640 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61  erface will alwa
37650 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
37660 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33  or..**.** {F1033
37670 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
37680 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
37690 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63  che(B)] interfac
376a0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
376b0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
376c0 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
376d0 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
376e0 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
376f0 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sfully..**.** {F
37700 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61  10339} Shared ca
37710 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
37720 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69  by default..*/.i
37730 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
37740 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
37750 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
37760 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
37770 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
37780 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a  y {F17340}.**.**
37790 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   The sqlite3_rel
377a0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
377b0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
377c0 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
377d0 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
377e0 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
377f0 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
37800 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37810 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
37820 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
37830 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f  ary. {END}  Memo
37840 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65  ry used to cache
37850 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
37860 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
37870 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
37880 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65  example of non-e
37890 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e  ssential memory.
378a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  .** sqlite3_rele
378b0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
378c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
378d0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
378e0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
378f0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
37900 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
37910 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
37920 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
37930 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  NTS:.**.** {F173
37940 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
37950 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37960 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74  N)] interface at
37970 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20  tempts to.**    
37980 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 74        free N byt
37990 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
379a0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
379b0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a  g non-essential.
379c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
379d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68  ry allocations h
379e0 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
379f0 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ase library..**.
37a00 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20  ** {F16342} The 
37a10 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
37a20 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75  _memory(N)] retu
37a30 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  rns the number.*
37a40 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 79  *          of by
37a50 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
37a60 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  ed, which might 
37a70 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a  be more or less.
37a80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
37a90 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
37aa0 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ested..*/.int sq
37ab0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37ac0 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
37ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f  * CAPI3REF: Impo
37ae0 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
37af0 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d  ap Size {F17350}
37b00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37b10 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37b20 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70  it() interface p
37b30 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
37b40 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61  imit.** on the a
37b50 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
37b60 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
37b70 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
37b80 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69  Lite..** If an i
37b90 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
37ba0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
37bb0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
37bc0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
37bd0 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
37be0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
37bf0 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
37c00 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
37c10 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
37c20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
37c30 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
37c40 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
37c50 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69  *.** The limit i
37c60 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c  s called "soft",
37c70 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
37c80 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37c90 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
37ca0 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
37cb0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
37cc0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
37cd0 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
37ce0 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
37cf0 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
37d00 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
37d10 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
37d20 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  oceeds..**.** A 
37d30 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
37d40 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
37d50 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
37d60 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
37d70 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
37d80 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37d90 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
37da0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
37db0 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
37dc0 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ed..** The defau
37dd0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
37de0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37df0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
37e00 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
37e10 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
37e20 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
37e30 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20  p limit..** But 
37e40 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  if the soft heap
37e50 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65   limit cannot be
37e60 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74   honored, execut
37e70 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
37e80 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
37e90 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
37ea0 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
37eb0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a   the limit is.**
37ec0 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
37ed0 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
37ee0 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
37ef0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
37f00 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
37f10 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
37f20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
37f30 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
37f40 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
37f50 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
37f60 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
37f70 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
37f80 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
37f90 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
37fa0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
37fb0 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
37fc0 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
37fd0 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
37fe0 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
37ff0 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
38000 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
38010 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
38020 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
38030 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
38040 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
38050 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
38060 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
38070 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
38080 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
38090 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
380a0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
380b0 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  reads..**.** INV
380c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
380d0 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16351} The [sql
380e0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
380f0 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61  imit(N)] interfa
38100 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74  ce places a soft
38110 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20   limit.**       
38120 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e     of N bytes on
38130 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
38140 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
38150 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
38160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69  .**          usi
38170 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
38180 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
38190 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20  3_realloc()] at 
381a0 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20  any point.**    
381b0 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a        in time..*
381c0 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66  *.** {F16352} If
381d0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
381e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
381f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
38200 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20  c()] would.**   
38210 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65         cause the
38220 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66   total amount of
38230 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72   allocated memor
38240 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a  y to exceed the.
38250 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74  **          soft
38260 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65   heap limit, the
38270 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  n [sqlite3_relea
38280 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
38290 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20  invoked.**      
382a0 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70      in an attemp
382b0 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20  t to reduce the 
382c0 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69  memory usage pri
382d0 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67  or to proceeding
382e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
382f0 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  h the memory all
38300 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e  ocation attempt.
38310 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20  .**.** {F16353} 
38320 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
38330 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
38340 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
38350 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a  )] that trigger.
38360 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65  **          atte
38370 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d  mpts to reduce m
38380 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f  emory usage thro
38390 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61  ugh the soft hea
383a0 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  p limit.**      
383b0 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f      mechanism co
383c0 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74  ntinue even if t
383d0 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  he attempt to re
383e0 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  duce memory.**  
383f0 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73          usage is
38400 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a   unsuccessful..*
38410 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20  *.** {F16354} A 
38420 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
38430 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20   value for N in 
38440 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
38450 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
38460 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
38470 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  )] means that th
38480 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a  ere is no soft.*
38490 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20  *          heap 
384a0 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74  limit and [sqlit
384b0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
384c0 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
384d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
384e0 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
384f0 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65   is completely e
38500 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  xhausted..**.** 
38510 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66  {F16355} The def
38520 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
38530 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
38540 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
38550 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20  * {F16358} Each 
38560 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
38570 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
38580 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  (N)] overrides t
38590 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
385a0 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c  alues set by all
385b0 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f   prior calls..*/
385c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f  .void sqlite3_so
385d0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
385e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
385f0 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74  REF: Extract Met
38600 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f  adata About A Co
38610 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20  lumn Of A Table 
38620 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12850}.**.** T
38630 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
38640 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f  rns metadata abo
38650 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
38660 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
38670 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74  ic.** database t
38680 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
38690 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62  using the [datab
386a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
386b0 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64  handle.** passed
386c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
386d0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
386e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d  .**.** The colum
386f0 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
38700 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
38710 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
38720 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a  parameters to.**
38730 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
38740 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
38750 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
38760 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
38770 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
38780 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20   "main", "temp" 
38790 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
387a0 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
387b0 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
387c0 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
387d0 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c  LL. If it is NUL
387e0 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
387f0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
38800 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
38810 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
38820 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
38830 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
38840 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
38850 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
38860 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
38870 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
38880 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
38890 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
388a0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
388b0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
388c0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
388d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
388e0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
388f0 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
38900 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
38910 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
38920 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
38930 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
38940 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
38950 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
38960 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
38970 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.