/ Hex Artifact Content
Login

Artifact bd32c7e159cf5f18f7de32d7e53a61e7218d4b53:


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 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 33 31 38 20 32 30 30 38 2f  in,v 1.318 2008/
05f0: 30 35 2f 32 33 20 31 37 3a 32 31 3a 30 39 20 73  05/23 17:21:09 s
0600: 68 61 6e 65 20 45 78 70 20 24 0a 2a 2f 0a 23 69  hane Exp $.*/.#i
0610: 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48  fndef _SQLITE3_H
0620: 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54  _.#define _SQLIT
0630: 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c  E3_H_.#include <
0640: 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a  stdarg.h>     /*
0650: 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20   Needed for the 
0660: 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61  definition of va
0670: 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  _list */../*.** 
0680: 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e  Make sure we can
0690: 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66   call this stuff
06a0: 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69   from C++..*/.#i
06b0: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
06c0: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
06d0: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
06e0: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
06f0: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
0700: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
0710: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0720: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0730: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0740: 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65  ./*.** Make sure
0750: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77   these symbols w
0760: 68 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64  here not defined
0770: 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75   by some previou
0780: 73 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65  s header.** file
0790: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
07a0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64  TE_VERSION.# und
07b0: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
07c0: 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  N.#endif.#ifdef 
07d0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
07e0: 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51  UMBER.# undef SQ
07f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0800: 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  BER.#endif../*.*
0810: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
0820: 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  ile-Time Library
0830: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
0840: 20 7b 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F10010}.**.** 
0850: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
0860: 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45  ON and SQLITE_VE
0870: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65  RSION_NUMBER #de
0880: 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20  fines in.** the 
0890: 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73  sqlite3.h file s
08a0: 70 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69  pecify the versi
08b0: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74  on of SQLite wit
08c0: 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20  h which.** that 
08d0: 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61  header file is a
08e0: 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  ssociated..**.**
08f0: 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f   The "version" o
0900: 66 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74  f SQLite is a st
0910: 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d  ring of the form
0920: 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65   "X.Y.Z"..** The
0930: 20 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20   phrase "alpha" 
0940: 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20  or "beta" might 
0950: 62 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65  be appended afte
0960: 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20  r the Z..** The 
0970: 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72  X value is major
0980: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
0990: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
09a0: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61  te3..** The X va
09b0: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  lue only changes
09c0: 20 77 68 65 6e 20 20 62 61 63 6b 77 61 72 64 73   when  backwards
09d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69   compatibility i
09e0: 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20  s.** broken and 
09f0: 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76  we intend to nev
0a00: 65 72 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b  er break.** back
0a10: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
0a20: 69 74 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75  ity.  The Y valu
0a30: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0a40: 65 72 73 69 6f 6e 0a 2a 2a 20 6e 75 6d 62 65 72  ersion.** number
0a50: 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65   and only change
0a60: 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  s when.** there 
0a70: 61 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72  are major featur
0a80: 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74  e enhancements t
0a90: 68 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 73  hat are forwards
0aa0: 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62   compatible.** b
0ab0: 75 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73  ut not backwards
0ac0: 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68   compatible.  Th
0ad0: 65 20 5a 20 76 61 6c 75 65 20 69 73 20 72 65 6c  e Z value is rel
0ae0: 65 61 73 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 61  ease number.** a
0af0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0b00: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0b10: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0b20: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0b30: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65   Y is incremente
0b40: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
0b50: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
0b60: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
0b70: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0b80: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a  n_number()]..**.
0b90: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
0ba0: 2a 0a 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68  *.** {F10011} Th
0bb0: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0bc0: 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20   #define in the 
0bd0: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0be0: 20 66 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20   file.**        
0bf0: 20 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61    evaluates to a
0c00: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0c10: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0c20: 74 65 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20  te version.**   
0c30: 20 20 20 20 20 20 20 77 69 74 68 20 77 68 69 63         with whic
0c40: 68 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  h the header fil
0c50: 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e  e is associated.
0c60: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20  .**.** {F10014} 
0c70: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
0c80: 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e  ON_NUMBER #defin
0c90: 65 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e  e resolves to an
0ca0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
0cb0: 20 20 20 20 20 77 69 74 68 20 74 68 65 20 76 61       with the va
0cc0: 6c 75 65 20 20 28 58 2a 31 30 30 30 30 30 30 20  lue  (X*1000000 
0cd0: 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68  + Y*1000 + Z) wh
0ce0: 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a  ere X, Y, and.**
0cf0: 20 20 20 20 20 20 20 20 20 20 5a 20 61 72 65 20            Z are 
0d00: 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f  the major versio
0d10: 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e  n, minor version
0d20: 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75  , and release nu
0d30: 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  mber..*/.#define
0d40: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
0d50: 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d          "--VERS-
0d60: 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  -".#define SQLIT
0d70: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0d80: 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42    --VERSION-NUMB
0d90: 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ER--../*.** CAPI
0da0: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
0db0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0dc0: 75 6d 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a  umbers {F10020}.
0dd0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
0de0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
0df0: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65  ** These feature
0e00: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
0e10: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0e20: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
0e30: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53  RSION].** and [S
0e40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0e50: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69  MBER] #defines i
0e60: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75  n the header, bu
0e70: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
0e80: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62  .** with the lib
0e90: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
0ea0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
0eb0: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72    Cautious progr
0ec0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20  ammers might.** 
0ed0: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20  include a check 
0ee0: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
0ef0: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74  tion to verify t
0f00: 68 61 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  hat .** 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 20 0a 2a 2a  ns the value .**
0f40: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0f50: 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  _NUMBER]..**.** 
0f60: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
0f70: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
0f80: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  n returns the sa
0f90: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0fa0: 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  s is.** in the s
0fb0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
0fc0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
0fd0: 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
0fe0: 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  is provided.** f
0ff0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
1000: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
1010: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1020: 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ve direct access
1030: 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f   to string.** co
1040: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1050: 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  he DLL..**.** IN
1060: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1070: 7b 46 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71  {F10021} The [sq
1080: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1090: 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72  _number()] inter
10a0: 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20  face returns an 
10b0: 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
10c0: 20 20 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51      equal to [SQ
10d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
10e0: 42 45 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31  BER]. .**.** {F1
10f0: 30 30 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  0022} The [sqlit
1100: 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69  e3_version] stri
1110: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74  ng constant cont
1120: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66  ains the text of
1130: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1140: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1150: 5d 20 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a  ] string. .**.**
1160: 20 7b 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73   {F10023} The [s
1170: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1180: 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  n()] function re
1190: 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
11a0: 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74    a pointer to t
11b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73  he [sqlite3_vers
11c0: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  ion] string cons
11d0: 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tant..*/.SQLITE_
11e0: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
11f0: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1200: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1210: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1220: 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ion(void);.int s
1230: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1240: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1250: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1260: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
1270: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
1280: 68 72 65 61 64 73 61 66 65 20 7b 46 31 30 31 30  hreadsafe {F1010
1290: 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
12a0: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
12b0: 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20  with or without 
12c0: 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a  mutexes.  When.*
12d0: 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52  * the SQLITE_THR
12e0: 45 41 44 53 41 46 45 20 43 20 70 72 65 70 72 6f  EADSAFE C prepro
12f0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1300: 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  true, mutexes.**
1310: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
1320: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
1330: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61  dsafe.  When tha
1340: 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65  t macro is false
1350: 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  ,.** the mutexes
1360: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1370: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1380: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1390: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
13a0: 69 74 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  ite from more th
13b0: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
13c0: 2a 0a 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20  *.** There is a 
13d0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
13e0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66  rmance penalty f
13f0: 6f 72 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65  or enabling mute
1400: 78 65 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  xes..** So if sp
1410: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1420: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1430: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1440: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1450: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1460: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1470: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1480: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
1490: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
14a0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
14b0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
14c0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
14d0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
14e0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
14f0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
1500: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
1510: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1520: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1530: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
1540: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
1550: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
1560: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45   the SQLITE_THRE
1570: 41 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a  ADSAFE macro..**
1580: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1590: 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54  **.** {F10101} T
15a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
15b0: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
15c0: 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65  on returns nonze
15d0: 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  ro if.**        
15e0: 20 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d    SQLite was com
15f0: 70 69 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d  piled with its m
1600: 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f  utexes enabled o
1610: 72 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20  r zero.**       
1620: 20 20 20 69 66 20 53 51 4c 69 74 65 20 77 61 73     if SQLite was
1630: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1640: 75 74 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e  utexes disabled.
1650: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1660: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
1670: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1680: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
1690: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46  ection Handle {F
16a0: 31 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  12000}.** KEYWOR
16b0: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f  DS: {database co
16c0: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62  nnection} {datab
16d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d  ase connections}
16e0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e  .**.** Each open
16f0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1700: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
1710: 62 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  by pointer to an
1720: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
1730: 0a 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63  .** opaque struc
1740: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
1750: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
1760: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
1770: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
1780: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
1790: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
17a0: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
17b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
17c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
17d0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
17e0: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
17f0: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64  structors.** and
1800: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1810: 29 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75  )] is its destru
1820: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1830: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1840: 72 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20  rfaces.** (such 
1850: 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  as [sqlite3_prep
1860: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1870: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1880: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1890: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
18a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
18b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
18c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74  are methods on t
18d0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a  his.** object..*
18e0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
18f0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
1900: 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1910: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
1920: 65 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30  er Types {F10200
1930: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  }.** KEYWORDS: s
1940: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
1950: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
1960: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
1970: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
1980: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
1990: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
19a0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
19b0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
19c0: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
19d0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
19e0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
19f0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
1a00: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
1a10: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
1a20: 72 65 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a  referred type.**
1a30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54   definitions.  T
1a40: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
1a50: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
1a60: 34 20 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73  4 types are.** s
1a70: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
1a80: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1a90: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
1aa0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1ab0: 2a 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20  ** {F10201} The 
1ac0: 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61  [sqlite_int64] a
1ad0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36  nd [sqlite3_int6
1ae0: 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66 79  4] types specify
1af0: 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36   a.**          6
1b00: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
1b10: 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  eger..**.** {F10
1b20: 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  202} The [sqlite
1b30: 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  _uint64] and [sq
1b40: 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79  lite3_uint64] ty
1b50: 70 65 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20  pes specify.**  
1b60: 20 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74          a 64-bit
1b70: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1b80: 72 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  r..*/.#ifdef SQL
1b90: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
1ba0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
1bb0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
1bc0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
1bd0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
1be0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
1bf0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
1c00: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
1c10: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
1c20: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
1c30: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
1c40: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
1c50: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
1c60: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
1c70: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
1c80: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
1c90: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
1ca0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1cb0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
1cc0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
1cd0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
1ce0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
1cf0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
1d00: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
1d10: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
1d20: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
1d30: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
1d40: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
1d50: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
1d60: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
1d70: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
1d80: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
1d90: 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53  oint.*/.#ifdef S
1da0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
1db0: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
1dc0: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
1dd0: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
1de0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1df0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
1e00: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46  se Connection {F
1e10: 31 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12010}.**.** Thi
1e20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  s routine is the
1e30: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
1e40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1e50: 6a 65 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70  ject.  .**.** Ap
1e60: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
1e70: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
1e80: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
1e90: 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  all.** [prepared
1ea0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64   statements] and
1eb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1ec0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
1ed0: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c   all [sqlite3_bl
1ee0: 6f 62 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20  ob | BLOBs] .** 
1ef0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1f00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
1f10: 6a 65 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f  ject prior.** to
1f20: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
1f30: 6c 6f 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65  lose the [sqlite
1f40: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  3] object..**.**
1f50: 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70   <todo>What happ
1f60: 65 6e 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74  ens to pending t
1f70: 72 61 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72  ransactions?  Ar
1f80: 65 20 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64  e they.** rolled
1f90: 20 62 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f   back, or abando
1fa0: 6e 65 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  ned?</todo>.**.*
1fb0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1fc0: 0a 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65  .** {F12011} The
1fd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1fe0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
1ff0: 74 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65  troys an [sqlite
2000: 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20  3] object.**    
2010: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20        allocated 
2020: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
2030: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2040: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
2050: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2060: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
2070: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  _open_v2()]..**.
2080: 2a 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20  ** {F12012} The 
2090: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20a0: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61  ] function relea
20b0: 73 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75  ses all memory u
20c0: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  sed by the.**   
20d0: 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f         connectio
20e0: 6e 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c  n and closes all
20f0: 20 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a   open files..**.
2100: 2a 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74  ** {F12013} If t
2110: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2120: 65 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a  ection contains.
2130: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2140: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2150: 5d 20 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20  ] that have not 
2160: 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  been.**         
2170: 20 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73   finalized by [s
2180: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2190: 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  )], then [sqlite
21a0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20  3_close()].**   
21b0: 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b         returns [
21c0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
21d0: 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e   leaves the conn
21e0: 65 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a  ection open..**.
21f0: 2a 2a 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69  ** {F12014} Givi
2200: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
2210: 28 29 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  () a NULL pointe
2220: 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2230: 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  no-op..**.** LIM
2240: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
2250: 7b 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72  {U12015} The par
2260: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2270: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74  e3_close()] must
2280: 20 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   be an [sqlite3]
2290: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
22a0: 20 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76      pointer prev
22b0: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
22c0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
22d0: 65 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a  en()] or the .**
22e0: 20 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61            equiva
22f0: 6c 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  lent, or NULL..*
2300: 2a 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68  *.** {U12016} Th
2310: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  e parameter to [
2320: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2330: 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2340: 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  een previously.*
2350: 2a 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65  *          close
2360: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2370: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2380: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2390: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
23a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
23b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
23c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
23d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
23e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
23f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2400: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2410: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2420: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2430: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2440: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2450: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2460: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2470: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2480: 74 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d  terface {F12100}
2490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
24b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
24c0: 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69  ent way of runni
24d0: 6e 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  ng.** one or mor
24e0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
24f0: 20 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f   without a lot o
2500: 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a  f C code.  The.*
2510: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2520: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2530: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2540: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
2550: 69 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68  ite3_exec().  Th
2560: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2570: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2580: 79 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65  y one.** until e
2590: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
25a0: 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  r an interrupt i
25b0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72  s encountered or
25c0: 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61  .** until they a
25d0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68  re all done.  Th
25e0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
25f0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a  is an optional.*
2600: 2a 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20  * callback that 
2610: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
2620: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
2630: 61 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74  any query result
2640: 73 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79  s.** produced by
2650: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2660: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61  nts.  The 5th pa
2670: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68  rameter tells wh
2680: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20  ere.** to write 
2690: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
26a0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72  es..**.** The er
26b0: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73  ror message pass
26c0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
26d0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
26e0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20  r is held.** in 
26f0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2700: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2710: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f  lloc()].  To avo
2720: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
2730: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67  ,.** the calling
2740: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
2750: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  uld call [sqlite
2760: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79  3_free()] on any
2770: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2780: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  e returned throu
2790: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
27a0: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73  eter when it has
27b0: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a   finished using.
27c0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
27d0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sage..**.** If t
27e0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
27f0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61   in the 2nd para
2800: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72  meter is NULL or
2810: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
2820: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20  .** or a string 
2830: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20  containing only 
2840: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63  whitespace and c
2850: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 53 51  omments, then SQ
2860: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2870: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2880: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2890: 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  s unchanged..**.
28a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
28b0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
28c0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69  is implemented i
28d0: 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73  n terms of.** [s
28e0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28f0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2900: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2910: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2920: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2930: 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20  _exec() routine 
2940: 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20  does nothing to 
2950: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61  the database tha
2960: 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65  t cannot be done
2970: 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
2980: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2990: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
29a0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
29b0: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  nalize()]..**.**
29c0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20   INVARIANTS:.** 
29d0: 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73  .** {F12101} A s
29e0: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
29f0: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2a00: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
2a10: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
2a20: 61 6c 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c  all evaluate all
2a30: 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e   of the UTF-8 en
2a40: 63 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e  coded, semicolon
2a50: 2d 73 65 70 61 72 61 74 65 64 2c 0a 2a 2a 20 20  -separated,.**  
2a60: 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74          SQL stat
2a70: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
2a80: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
2a90: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
2aa0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2ab0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 44 20 5b  ntext of the D [
2ac0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ad0: 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ion]..**.** {F12
2ae0: 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61  102} If the S pa
2af0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2b00: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
2b10: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65  ,E)] is NULL the
2b20: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
2b30: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  e actions of the
2b40: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2b50: 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20   be the same as 
2b60: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
2b70: 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77     S parameter w
2b80: 68 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74  here an empty st
2b90: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ring..**.** {F12
2ba0: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
2bb0: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
2bc0: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
2bd0: 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  be [SQLITE_OK] i
2be0: 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  f all.**        
2bf0: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
2c00: 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c   run successfull
2c10: 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74  y and to complet
2c20: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ion..**.** {F121
2c30: 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  05} The return v
2c40: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2c50: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
2c60: 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  e an appropriate
2c70: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f   .**          no
2c80: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
2c90: 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73  de] if any SQL s
2ca0: 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a  tatement fails..
2cb0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49  **.** {F12107} I
2cc0: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
2cd0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ce0: 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73  nts handed to [s
2cf0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
2d00: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2d10: 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68  n results and th
2d20: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2d30: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
2d40: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
2d50: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2d60: 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
2d70: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2d80: 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20  er shall be.**  
2d90: 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20          invoked 
2da0: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f  once for each ro
2db0: 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a  w of result..**.
2dc0: 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74  ** {F12110} If t
2dd0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
2de0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76  rns a non-zero v
2df0: 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74  alue then [sqlit
2e00: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
2e10: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f         shall abo
2e20: 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
2e30: 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65  ment it is curre
2e40: 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c  ntly evaluating,
2e50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69  .**          ski
2e60: 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  p all subsequent
2e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c   SQL statements,
2e80: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
2e90: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
2ea0: 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b  * {F12113} The [
2eb0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2ec0: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61  routine shall pa
2ed0: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d  ss its 4th param
2ee0: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20  eter through.** 
2ef0: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
2f00: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66  1st parameter of
2f10: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2f20: 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68  *.** {F12116} Th
2f30: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2f40: 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  )] routine sets 
2f50: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f60: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
2f70: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
2f80: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
2f90: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2fa0: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
2fb0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
2fc0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2fd0: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
2fe0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2ff0: 73 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72  sets the 3rd par
3000: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a  ameter of its .*
3010: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
3020: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
3030: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3040: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
3050: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
3060: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63    values for eac
3070: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
3080: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73  current result s
3090: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20  et row as.**    
30a0: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
30b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
30c0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
30d0: 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20  ** {F12122} The 
30e0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
30f0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
3100: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3110: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3120: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3130: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3140: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3150: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
3160: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
3170: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
3180: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
3190: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
31a0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
31b0: 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68  * {F12125} If th
31c0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
31d0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
31e0: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
31f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3200: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65  lite3_exec()] ne
3210: 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61  ver invokes a ca
3220: 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65  llback.  All que
3230: 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ry.**          r
3240: 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e  esults are silen
3250: 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  tly discarded..*
3260: 2a 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66  *.** {F12131} If
3270: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3280: 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f   while parsing o
3290: 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79  r evaluating any
32a0: 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20   of the SQL.**  
32b0: 20 20 20 20 20 20 20 20 68 61 6e 64 65 64 20 69          handed i
32c0: 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65  n the S paramete
32d0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  r of [sqlite3_ex
32e0: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61  ec(D,S,C,A,E)] a
32f0: 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  nd if.**        
3300: 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 65    the E paramete
3310: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
3320: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  hen [sqlite3_exe
3330: 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65  c()] shall store
3340: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
3350: 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  *E an appropriat
3360: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3370: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
3380: 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ory obtained.** 
3390: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
33a0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33b0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d  ..**.** {F12134}
33c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
33d0: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72  ec(D,S,C,A,E)] r
33e0: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
33f0: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
3400: 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20            *E to 
3410: 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74  NULL if E is not
3420: 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20   NULL and there 
3430: 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a  are no errors..*
3440: 2a 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68  *.** {F12137} Th
3450: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3460: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63  D,S,C,A,E)] func
3470: 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74  tion shall set t
3480: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
3490: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65            and me
34a0: 73 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65  ssage accessible
34b0: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
34c0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
34d0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
34e0: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
34f0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3500: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  )]..**.** {F1213
3510: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3520: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3530: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3540: 29 5d 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20  )] is a null or 
3550: 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20  empty.**        
3560: 20 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74    string or cont
3570: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
3580: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
3590: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e  ce, comments, an
35a0: 64 2f 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  d/or.**         
35b0: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65   semicolons, the
35c0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71  n results of [sq
35d0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
35e0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
35f0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3600: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3610: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
3620: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73         shall res
3630: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e  et to indicate n
3640: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3650: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
3660: 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20  ** {U12141} The 
3670: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
3680: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3690: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76  ()] must be an v
36a0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a  alid and open.**
36b0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
36c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
36d0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20  .**.** {U12142} 
36e0: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
36f0: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
3700: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65   be closed while
3710: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3720: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3730: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a   running..** .**
3740: 20 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61   {U12143} The ca
3750: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  lling function s
3760: 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74  hould use [sqlit
3770: 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72  e3_free()] to fr
3780: 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ee.**          t
3790: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a  he memory that *
37a0: 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70  errmsg is left p
37b0: 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20  ointing at once 
37c0: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  the error.**    
37d0: 20 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73        message is
37e0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
37f0: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35  d..**.** {U12145
3800: 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d  } The SQL statem
3810: 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20  ent text in the 
3820: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3830: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3840: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75  ].**          mu
3850: 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  st remain unchan
3860: 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ged while [sqlit
3870: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75  e3_exec()] is ru
3880: 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
3890: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
38a0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
38d0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
38e0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
38f0: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
3900: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3910: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74  SQL to be evalut
3920: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
3930: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3940: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
3950: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
3960: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3970: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
39a0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
39b0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
39c0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
39f0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3a00: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
3a10: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
3a20: 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45  s {F10210}.** KE
3a30: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
3a40: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
3a50: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a  error codes}.**.
3a60: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
3a70: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
3a80: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
3a90: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
3aa0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3ab0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3ac0: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3ad0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3ae0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
3af0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
3b00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3b10: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
3b20: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3b30: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3b40: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3b50: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3b60: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3b70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b80: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3b90: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3ba0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3bb0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3bc0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3bd0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
3be0: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
3bf0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
3c00: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
3c10: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
3c20: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
3c30: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3c40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
3c50: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
3c60: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
3c70: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
3c80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3c90: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
3ca0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
3cb0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
3cc0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3cd0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
3ce0: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
3cf0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
3d00: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
3d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
3d20: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
3d30: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
3d40: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d50: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
3d60: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
3d70: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
3d80: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
3d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3da0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
3db0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
3dc0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
3dd0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
3de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3df0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
3e00: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
3e10: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
3e20: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
3e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
3e40: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
3e50: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
3e60: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
3e70: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
3e80: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
3e90: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
3ea0: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
3eb0: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
3ee0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
3ef0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
3f00: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
3f10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f20: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
3f30: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
3f40: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
3f50: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
3f60: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
3f70: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
3f80: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
3f90: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
3fa0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
3fb0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
3fc0: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
3fd0: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
3fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
3ff0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4000: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4010: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4030: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4040: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4050: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4060: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4070: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4080: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4090: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
40a0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
40c0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
40d0: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
40e0: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
40f0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4100: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4110: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4120: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4130: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4140: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4150: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4160: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4170: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4180: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4190: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
41a0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
41b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
41c0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
41d0: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
41e0: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
41f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4200: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4210: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4220: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4230: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4240: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4250: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4260: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4270: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4280: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4290: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42a0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
42b0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
42c0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
42d0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
42e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
42f0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4300: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4310: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4320: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4330: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4340: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4350: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4360: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30  esult Codes {F10
4370: 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  220}.** KEYWORDS
4380: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  : {extended erro
4390: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  r code} {extende
43a0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a  d error codes}.*
43b0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
43c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43d0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
43e0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
43f0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4400: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4410: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4420: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4430: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4440: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4450: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4460: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20  wn that.** many 
4470: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  of these result 
4480: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4490: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  urse-grained.  T
44a0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
44b0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
44c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
44d0: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
44e0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
44f0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4500: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4510: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4520: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4530: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4540: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4550: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4560: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4570: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4580: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4590: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
45a0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
45b0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
45c0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
45d0: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
45e0: 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61  d.** for each da
45f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4600: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
4610: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4620: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a  sult_codes()].**
4630: 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d   API..** .** Som
4640: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4650: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4660: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4670: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4680: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4690: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
46a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
46b0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
46c0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
46d0: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
46e0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
46f0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4700: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4710: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4720: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4730: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4740: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4750: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4760: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4770: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4780: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4790: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a  tly zero..** .**
47a0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
47b0: 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20  ** {F10223} The 
47c0: 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f  symbolic name fo
47d0: 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  r an extended re
47e0: 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73  sult code always
47f0: 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
4800: 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64 20        a related 
4810: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4820: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
4830: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20  .**.** {F10224} 
4840: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  Primary result c
4850: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
4860: 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63  n a single "_" c
4870: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  haracter..**.** 
4880: 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65  {F10225} Extende
4890: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  d result code na
48a0: 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20  mes contain two 
48b0: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72  or more "_" char
48c0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  acters..**.** {F
48d0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72  10226} The numer
48e0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65  ic value of an e
48f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4900: 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ode contains the
4910: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
4920: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74  eric value of it
4930: 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  s corresponding 
4940: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4950: 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ode in.**       
4960: 20 20 20 69 74 73 20 6c 65 61 73 74 20 73 69 67     its least sig
4970: 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e  nificant 8 bits.
4980: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4990: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
49a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
49b0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
49c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
49d0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
49e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
49f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4a00: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4a10: 52 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51  RITE         (SQ
4a20: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4a30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4a40: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4a50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4a60: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
4a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4a80: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
4a90: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4aa0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ac0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53  TRUNCATE      (S
4ad0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4ae0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4af0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4b00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b10: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
4b40: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b50: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
4b60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b70: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28  _RDLOCK        (
4b80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4b90: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
4ba0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
4bb0: 54 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  TE        (SQLIT
4bc0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
4c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4c20: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
4c30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c40: 7c 20 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a  | (12<<8))../*.*
4c50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
4c60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
4c70: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32  Operations {F102
4c80: 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  30}.**.** These 
4c90: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
4ca0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
4cb0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
4cc0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
4cd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4ce0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
4cf0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
4d00: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4d10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
4d20: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4d30: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  vfs] object..*/.
4d40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4d50: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
4d60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
4d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4d80: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
4d90: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
4da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4db0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
4dc0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
4dd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4de0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
4df0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a  E    0x00000008.
4e00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e10: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
4e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
4e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e40: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
4e50: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
4e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e70: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
4e80: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
4e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ea0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
4eb0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
4ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ed0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
4ee0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a       0x00000800.
4ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f00: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
4f10: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a       0x00001000.
4f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f30: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
4f40: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
4f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f60: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
4f70: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a  AL   0x00004000.
4f80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4f90: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
4fa0: 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d  ristics {F10240}
4fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
4fc0: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d  ceCapabilities m
4fd0: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
4fe0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4ff0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
5000: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
5010: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
5020: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
5030: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
5040: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5050: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5060: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5070: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5080: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5090: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
50a0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
50b0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
50c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
50d0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
50e0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
50f0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
5100: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5110: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5120: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5130: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5140: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5150: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5160: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5170: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5180: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5190: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
51a0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
51b0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
51c0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
51d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
51e0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
51f0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
5200: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5210: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5220: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5230: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5240: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5250: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5260: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5270: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5280: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5290: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
52a0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
52b0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
52c0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
52d0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
52e0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
52f0: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  te()..*/.#define
5300: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5310: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78  OMIC          0x
5320: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5340: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78  OMIC512       0x
5350: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
5360: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5370: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78  OMIC1K        0x
5380: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5390: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53a0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78  OMIC2K        0x
53b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
53c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78  OMIC4K        0x
53e0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5400: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78  OMIC8K        0x
5410: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
5420: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5430: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78  OMIC16K       0x
5440: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5450: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5460: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78  OMIC32K       0x
5470: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
5480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5490: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78  OMIC64K       0x
54a0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
54c0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78  FE_APPEND     0x
54d0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
54e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
54f0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78  QUENTIAL      0x
5500: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20  00000400../*.** 
5510: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
5520: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46  ocking Levels {F
5530: 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  10250}.**.** SQL
5540: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
5550: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5560: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5570: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
5580: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
5590: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
55a0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
55b0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
55c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
55d0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
55e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
55f0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
5600: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
5610: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
5620: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
5630: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
5640: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
5650: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
5660: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
5670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5680: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
5690: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
56a0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
56b0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
56c0: 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68  F10260}.**.** Wh
56d0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
56e0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
56f0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5700: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5710: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5720: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5730: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5740: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5750: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5760: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5770: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5780: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5790: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
57a0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
57b0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
57c0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
57d0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
57e0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
57f0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5800: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68  t be flushed. Th
5810: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
5820: 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20  RMAL flag means 
5830: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
5840: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
5850: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
5860: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
5870: 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20  eans .** to use 
5880: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  Mac OS-X style f
5890: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
58a0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
58b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
58c0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
58d0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
58e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
58f0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
5900: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
5910: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5920: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f       0x00010.../
5930: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5940: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5950: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31   File Handle {F1
5960: 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  1110}.**.** An [
5970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
5980: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
5990: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
59a0: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
59b0: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
59c0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
59d0: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
59e0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
59f0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
5a00: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
5a10: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
5a20: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
5a30: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
5a40: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
5a50: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
5a60: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
5a70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5a80: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
5a90: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
5aa0: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
5ab0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
5ac0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
5ad0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
5ae0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
5af0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
5b00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
5b10: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
5b20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5b30: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
5b40: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
5b50: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
5b60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5b70: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
5b80: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
5b90: 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30  s Object {F11120
5ba0: 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  }.**.** Every fi
5bb0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
5bc0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
5bd0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
5be0: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
5bf0: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
5c00: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
5c10: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65    This object de
5c20: 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74  fines the.** met
5c30: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
5c40: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
5c50: 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20  rations against 
5c60: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5c70: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
5c80: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
5c90: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
5ca0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5cb0: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
5cc0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
5cd0: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
5ce0: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
5cf0: 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65  ync()..*  The se
5d00: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
5d10: 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20  n.** OS-X style 
5d20: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53  fullsync.  The S
5d30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20  QLITE_SYNC_DATA 
5d40: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
5d50: 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61   in to.** indica
5d60: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
5d70: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
5d80: 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  e and not its in
5d90: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a  ode needs to be.
5da0: 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a  ** synced..** .*
5db0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
5dc0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
5dd0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
5de0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
5df0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5e00: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
5e10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5e20: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
5e30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5e40: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
5e50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5e60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
5e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5e80: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5e90: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5ea0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5eb0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5ec0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5ed0: 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68  ck.  .** The xCh
5ee0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
5ef0: 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a  ) method looks.*
5f00: 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20  * to see if any 
5f10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5f20: 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74  ion, either in t
5f30: 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f  his.** process o
5f40: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
5f50: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
5f60: 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c  ing an RESERVED,
5f70: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
5f80: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
5f90: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
5fa0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
5fb0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
5fc0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
5fd0: 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54  if not..** .** T
5fe0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
5ff0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
6000: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
6010: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
6020: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
6030: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
6040: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
6050: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
6060: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6070: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
6080: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
6090: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
60a0: 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69  ument.** is an i
60b0: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
60c0: 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   The third.** ar
60d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
60e0: 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63  ric pointer whic
60f0: 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  h is intended to
6100: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   be a pointer.**
6110: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
6120: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
6130: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
6140: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
6150: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
6160: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6170: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6180: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6190: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
61a0: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
61b0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
61c0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
61d0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
61e0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
61f0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
6200: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
6210: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
6220: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
6230: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
6240: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6250: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6260: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6270: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
6280: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
6290: 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51  n use. .** A [SQ
62a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
62b0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
62c0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
62d0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
62e0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
62f0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6300: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6310: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
6320: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20  uld use opcodes 
6330: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6340: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6350: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6360: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6370: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6380: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6390: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
63a0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
63b0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
63c0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
63d0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
63e0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
63f0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6400: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6410: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6420: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6430: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6440: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6450: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6460: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6470: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6480: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6490: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
64a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
64b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
64c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
64d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
64e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
64f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
6500: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6510: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
6520: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6530: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
6540: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6550: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6580: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6590: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
65a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
65b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
65c0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
65d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
65e0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
65f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6600: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
6610: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
6620: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6630: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6640: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6650: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6660: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6670: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6680: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6690: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
66a0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
66b0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
66c0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
66d0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
66e0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
66f0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6700: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6710: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6720: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6730: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6740: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6750: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6760: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6770: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6780: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6790: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
67a0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
67b0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
67c0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
67d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
67e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
67f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6800: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6810: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6820: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6830: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6840: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
6850: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6860: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6870: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6880: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6890: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68a0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
68b0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
68c0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
68d0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
68e0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
68f0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
6900: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
6910: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
6920: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
6930: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
6940: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6950: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6960: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6970: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6990: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
69a0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
69b0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
69c0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
69d0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
69e0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
69f0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
6a00: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
6a10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6a20: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
6a30: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6a40: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6a50: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6a60: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6a70: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  e*);.  int (*xFi
6a80: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
6a90: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
6aa0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
6ab0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
6ac0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
6ad0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
6ae0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6af0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
6b00: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f  *);.  /* Additio
6b10: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
6b20: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
6b30: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
6b40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
6b50: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
6b60: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
6b70: 20 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F11310}.**.** 
6b80: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
6b90: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
6ba0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
6bb0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
6bc0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
6bd0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6be0: 62 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65  bject and to the
6bf0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
6c00: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
6c10: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
6c20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
6c30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
6c40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
6c50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
6c60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
6c70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
6c80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
6c90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
6ca0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
6cb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
6cc0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
6cd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6ce0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
6cf0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
6d00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6d10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
6d20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
6d30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
6d40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
6d50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
6d60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
6d70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
6d80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
6d90: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
6da0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
6db0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
6dc0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
6dd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6de0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6df0: 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a  E        1../*.*
6e00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
6e10: 78 20 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30  x Handle {F17110
6e20: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  }.**.** The mute
6e30: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
6e40: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
6e50: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
6e60: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
6e70: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
6e80: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
6e90: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
6ea0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
6eb0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
6ec0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
6ed0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
6ee0: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
6ef0: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
6f00: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
6f10: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
6f20: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
6f30: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
6f40: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
6f50: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
6f60: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6f70: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
6f80: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
6f90: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6fa0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
6fb0: 46 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e  F11140}.**.** An
6fc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
6fd0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
6fe0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
6ff0: 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51  etween the.** SQ
7000: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
7010: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
7020: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
7030: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
7040: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7050: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
7060: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
7070: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54  system"..**.** T
7080: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
7090: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
70a0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
70b0: 65 72 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a  er for future.**
70c0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
70d0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
70e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
70f0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7100: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7110: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7120: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a  e is increased..
7130: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
7140: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
7150: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
7160: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
7170: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
7180: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
7190: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
71a0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
71b0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
71c0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
71d0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
71e0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
71f0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
7200: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
7210: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
7220: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
7230: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
7240: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
7250: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
7260: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
7270: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
7280: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
7290: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
72a0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
72b0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
72c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
72d0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
72e0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  t..**.** The pNe
72f0: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
7300: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
7310: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a  e sqlite3_vfs .*
7320: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
7330: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
7340: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
7350: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
7360: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
7370: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
7380: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
7390: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
73a0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
73b0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
73c0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
73d0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
73e0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
73f0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
7400: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
7410: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
7420: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
7430: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
7440: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
7450: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
7460: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
7470: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
7480: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ules..**.** {F11
7490: 31 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  141} SQLite will
74a0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
74b0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74  the zFilename st
74c0: 72 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a  ring passed to.*
74d0: 2a 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66  * xOpen() is a f
74e0: 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20  ull pathname as 
74f0: 67 65 6e 65 72 61 74 65 64 20 62 79 20 78 46 75  generated by xFu
7500: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64  llPathname() and
7510: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74 72  .** that the str
7520: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
7530: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
7540: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
7550: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45  s.** called.  {E
7560: 4e 44 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69  ND} So the [sqli
7570: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74  te3_file] can st
7580: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
7590: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
75a0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
75b0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
75c0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
75d0: 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eason..**.** {F1
75e0: 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20  1142} The flags 
75f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
7600: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
7610: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
7620: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
7630: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
7640: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
7650: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
7660: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
7670: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
7680: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
7690: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
76a0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
76b0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
76c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
76d0: 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66  TE]. {END}.** If
76e0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
76f0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
7700: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
7710: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
7720: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
7730: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
7740: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
7750: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a  utFlags may be.*
7760: 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46  * set..** .** {F
7770: 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69  11143} SQLite wi
7780: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
7790: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
77a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
77b0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
77c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
77d0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
77e0: 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e  ned:.** .** <ul>
77f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7800: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
7810: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7820: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
7830: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
7840: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
7850: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
7860: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
7870: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
7880: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
7890: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
78a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
78b0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
78c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
78d0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
78e0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  L].** </ul> {END
78f0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  }.**.** The file
7900: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
7910: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
7920: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
7930: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20  s to.** changes 
7940: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
7950: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
7960: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
7970: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
7980: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
7990: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
79a0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
79b0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
79c0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
79d0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
79e0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
79f0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
7a00: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
7a10: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
7a20: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
7a30: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
7a40: 74 75 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f  turn .** SQLITE_
7a50: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
7a60: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
7a70: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
7a80: 61 74 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  at a database .*
7a90: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
7aa0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
7ab0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
7ac0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
7ad0: 61 6e 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20  andom .** order 
7ae0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
7af0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
7b00: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a  ordingly..** .**
7b10: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
7b20: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
7b30: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
7b40: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  s to the xOpen.*
7b50: 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a  * method:.** .**
7b60: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7b70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7b80: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
7b90: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
7ba0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
7bb0: 6c 3e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  l>.** .** {F1114
7bc0: 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  5} The [SQLITE_O
7bd0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7be0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
7bf0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
7c00: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
7c10: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
7c20: 7b 46 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51  {F11146} The [SQ
7c30: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7c40: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
7c50: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
7c60: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
7c70: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
7c80: 62 6a 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b  bjournals. .** {
7c90: 46 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c  F11147} The [SQL
7ca0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
7cb0: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
7cc0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
7cd0: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
7ce0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
7cf0: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
7d00: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
7d10: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
7d20: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
7d30: 65 20 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a  e file. {END}.**
7d40: 20 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74   .** {F11148} At
7d50: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
7d60: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
7d70: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
7d80: 20 53 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68   SQLite .** to h
7d90: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
7da0: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
7db0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
7dc0: 74 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65  third .** argume
7dd0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45  nt to xOpen.  {E
7de0: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ND}  The xOpen m
7df0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
7e00: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
7e10: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
7e20: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
7e30: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20   fill it in..** 
7e40: 0a 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65  .** {F11149} The
7e50: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7e60: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
7e70: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
7e80: 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74  SS_EXISTS] .** t
7e90: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
7ea0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
7eb0: 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  le,.** or [SQLIT
7ec0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
7ed0: 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73  TE] to test to s
7ee0: 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20  ee.** if a file 
7ef0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
7f00: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
7f10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7f20: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20  ].** to test to 
7f30: 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69 73  see if a file is
7f40: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
7f50: 6c 65 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66  le.  {END} The f
7f60: 69 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a  ile can be a .**
7f70: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a   directory..** .
7f80: 2a 2a 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69  ** {F11150} SQLi
7f90: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
7fa0: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
7fb0: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
7fc0: 74 65 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  tes for.** the o
7fd0: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
7fe0: 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61  r xGetTempname a
7ff0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
8000: 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65  . {F11151} The e
8010: 78 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  xact.** size of 
8020: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8030: 72 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  r is also passed
8040: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
8050: 74 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68  to both .** meth
8060: 6f 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68  ods. {END} If th
8070: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
8080: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8090: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
80a0: 54 4f 50 45 4e 5d 0a 2a 2a 20 73 68 6f 75 6c 64  TOPEN].** should
80b0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73   be returned. As
80c0: 20 74 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64   this is handled
80d0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
80e0: 72 20 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  r by SQLite,.** 
80f0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8100: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8110: 76 6f 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74  vor to prevent t
8120: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a  his by setting .
8130: 2a 2a 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ** mxPathname to
8140: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
8150: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20  large value..** 
8160: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8170: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
8180: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
8190: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
81a0: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
81b0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
81c0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
81d0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
81e0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
81f0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
8200: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
8210: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
8220: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
8230: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
8240: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
8250: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
8260: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
8270: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
8280: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
8290: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
82a0: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
82b0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20  ness obtained.  
82c0: 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20  The.** xSleep() 
82d0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
82e0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
82f0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
8300: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
8310: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
8320: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
8330: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
8340: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8350: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
8360: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
8370: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a  rrent date and.*
8380: 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  * time..*/.typed
8390: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
83a0: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
83b0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
83c0: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
83d0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
83e0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
83f0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
8400: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
8410: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
8420: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
8430: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
8440: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
8450: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
8460: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
8470: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
8480: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
8490: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
84a0: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
84b0: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
84c0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
84d0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
84e0: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
84f0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
8500: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
8510: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
8520: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
8530: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
8540: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
8550: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8560: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
8570: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
8580: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
8590: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
85a0: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
85b0: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
85c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
85d0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
85e0: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
85f0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
8600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8610: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
8620: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  ags);.  int (*xG
8630: 65 74 54 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69  etTempname)(sqli
8640: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f  te3_vfs*, int nO
8650: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
8660: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
8670: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
8680: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
8690: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
86a0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
86b0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
86c0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
86d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
86e0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
86f0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
8700: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
8710: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
8720: 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  sg);.  void *(*x
8730: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
8740: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
8750: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b   char *zSymbol);
8760: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
8770: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
8780: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
8790: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
87a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
87b0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
87c0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
87d0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
87e0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
87f0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
8800: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
8810: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
8820: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
8830: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
8840: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
8850: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
8860: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
8870: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
8880: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
8890: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
88a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
88b0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
88c0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b  ess VFS method {
88d0: 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F11190}.**.** {F
88e0: 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74  11191} These int
88f0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
8900: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
8910: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
8920: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
8930: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
8940: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
8950: 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68  bject. {END}  Th
8960: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
8970: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
8980: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
8990: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a  cess method is.*
89a0: 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20  * looking for.  
89b0: 7b 46 31 31 31 39 32 7d 20 57 69 74 68 20 5b 53  {F11192} With [S
89c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
89d0: 53 54 53 5d 2c 20 74 68 65 20 78 41 63 63 65 73  STS], the xAcces
89e0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
89f0: 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  ly checks to see
8a00: 20 69 66 20 74 68 65 20 66 69 6c 65 20 65 78 69   if the file exi
8a10: 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20 57 69  sts. {F11193} Wi
8a20: 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43  th.** SQLITE_ACC
8a30: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
8a40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8a50: 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 0a  d checks to see.
8a60: 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ** if the file i
8a70: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
8a80: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20 20 7b  and writable.  {
8a90: 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20  F11194} With.** 
8aa0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8ab0: 41 44 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  AD the xAccess m
8ac0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
8ad0: 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66 69  to see if the fi
8ae0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
8af0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8b00: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
8b10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
8b20: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
8b30: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
8b40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8b50: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
8b60: 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
8b70: 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
8b80: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
8b90: 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a  s {F12200}.**.**
8ba0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74   The sqlite3_ext
8bb0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
8bc0: 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
8bd0: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
8be0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
8bf0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
8c00: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
8c10: 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
8c20: 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20 65 78  QLite..** The ex
8c30: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
8c40: 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
8c50: 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
8c60: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
8c70: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
8c80: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
8c90: 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20 45 61  *.** {F12201} Ea
8ca0: 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
8cb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61   connection] sha
8cc0: 6c 6c 20 68 61 76 65 20 74 68 65 20 0a 2a 2a 20  ll have the .** 
8cd0: 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64           [extend
8ce0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
8cf0: 20 66 65 61 74 75 72 65 0a 2a 2a 20 20 20 20 20   feature.**     
8d00: 20 20 20 20 20 64 69 73 61 62 6c 65 64 20 62 79       disabled by
8d10: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
8d20: 7b 46 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71  {F12202} The [sq
8d30: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
8d40: 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29  esult_codes(D,F)
8d50: 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
8d60: 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20  l enable.**     
8d70: 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72       [extended r
8d80: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72  esult codes] for
8d90: 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
8da0: 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
8db0: 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 65  ection] D if the
8dc0: 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20   F parameter.** 
8dd0: 20 20 20 20 20 20 20 20 20 69 73 20 74 72 75 65           is true
8de0: 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  , or disable the
8df0: 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e  m if F is false.
8e00: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
8e10: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
8e20: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
8e30: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
8e40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
8e50: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
8e60: 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 61  F12220}.**.** Ea
8e70: 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
8e80: 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
8e90: 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
8ea0: 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
8eb0: 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
8ec0: 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f   "rowid". The ro
8ed0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
8ee0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
8ef0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
8f00: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
8f10: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
8f20: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
8f30: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
8f40: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
8f50: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
8f60: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a  ed columns. If.*
8f70: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
8f80: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
8f90: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
8fa0: 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63   KEY then that c
8fb0: 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
8fc0: 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
8fd0: 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54  e rowid..**.** T
8fe0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
8ff0: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66  rns the rowid of
9000: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
9010: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49  .** successful I
9020: 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64  NSERT into the d
9030: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
9040: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9050: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e  tion.** shown in
9060: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
9070: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63  ent.  If no succ
9080: 65 73 73 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a  essful inserts.*
9090: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
90a0: 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61 74  rred on this dat
90b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
90c0: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
90d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
90e0: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
90f0: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
9100: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
9110: 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65  f the.** inserte
9120: 64 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  d row is returne
9130: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
9140: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
9150: 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72   trigger.** is r
9160: 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63  unning.  But onc
9170: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
9180: 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
9190: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
91a0: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
91b0: 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
91c0: 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
91d0: 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  ed before the.**
91e0: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
91f0: 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20  **.** An INSERT 
9200: 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
9210: 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
9220: 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
9230: 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
9240: 69 6e 73 65 72 74 20 61 6e 64 20 64 6f 65 73 20  insert and does 
9250: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
9260: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
9270: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
9280: 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f  .  Thus INSERT O
9290: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
92a0: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
92b0: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
92c0: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
92d0: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
92e0: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
92f0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
9300: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
9310: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
9320: 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e   fails.  When IN
9330: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
9340: 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
9350: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
9360: 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
9370: 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
9380: 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
9390: 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
93a0: 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
93b0: 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
93c0: 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
93d0: 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
93e0: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
93f0: 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
9400: 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
9410: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
9420: 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20  terface. .**.** 
9430: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
9440: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
9450: 2c 20 61 6e 20 69 6e 73 65 72 74 20 69 73 20 63  , an insert is c
9460: 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
9470: 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
9480: 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
9490: 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
94a0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
94b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
94c0: 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  12221} The [sqli
94d0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
94e0: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
94f0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
9500: 20 20 20 20 20 20 20 20 20 20 72 6f 77 69 64 20            rowid 
9510: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
9520: 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e  nt successful in
9530: 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 20 20 20  sert done.**    
9540: 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
9550: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
9560: 63 74 69 6f 6e 20 61 6e 64 20 77 69 74 68 69 6e  ction and within
9570: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
9580: 20 20 20 20 20 20 6f 72 20 68 69 67 68 65 72 20        or higher 
9590: 6c 65 76 65 6c 20 74 72 69 67 67 65 72 20 63 6f  level trigger co
95a0: 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69  ntext, or zero i
95b0: 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20  f there have.** 
95c0: 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 6e 6f           been no
95d0: 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65   qualifying inse
95e0: 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  rts..**.** {F122
95f0: 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
9600: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
9610: 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  id()] function r
9620: 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
9630: 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68     same value wh
9640: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
9650: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20  he same trigger 
9660: 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
9670: 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20      immediately 
9680: 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72  before and after
9690: 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a   a ROLLBACK..**.
96a0: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
96b0: 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49  **.** {U12232} I
96c0: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
96d0: 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69  ead does a new i
96e0: 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d  nsert on the sam
96f0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
9700: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9710: 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
9720: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
9730: 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20  _rowid()].**    
9740: 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69        function i
9750: 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
9760: 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
9770: 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
9780: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
9790: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
97a0: 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
97b0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
97c0: 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20  wid()] is.**    
97d0: 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61        unpredicta
97e0: 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
97f0: 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
9800: 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
9810: 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  w.**          la
9820: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e  st insert rowid.
9830: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
9840: 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
9850: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
9860: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
9870: 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
9880: 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
9890: 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34   Modified {F1224
98a0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
98b0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
98c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
98d0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
98e0: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
98f0: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
9900: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
9910: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
9920: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
9930: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f  ent.** on the co
9940: 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
9950: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
9960: 70 61 72 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79  parameter.  Only
9970: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74  .** changes that
9980: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
9990: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
99a0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
99b0: 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74  r.** DELETE stat
99c0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
99d0: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
99e0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
99f0: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
9a00: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
9a10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
9a20: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
9a30: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
9a40: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
9a50: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
9a60: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
9a70: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
9a80: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
9a90: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
9aa0: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
9ab0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
9ac0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
9ad0: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
9ae0: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
9af0: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
9b00: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
9b10: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
9b20: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
9b30: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
9b40: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
9b50: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
9b60: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
9b70: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
9b80: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
9b90: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
9ba0: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
9bb0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
9bc0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
9bd0: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
9be0: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
9bf0: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
9c00: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
9c10: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
9c20: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
9c30: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
9c40: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
9c50: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
9c60: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
9c70: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
9c80: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
9c90: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
9ca0: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
9cb0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
9cc0: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
9cd0: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
9ce0: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
9cf0: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
9d00: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
9d10: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
9d20: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
9d30: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
9d40: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
9d50: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
9d60: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
9d70: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
9d80: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
9d90: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
9da0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
9db0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
9dc0: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
9dd0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
9de0: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
9df0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
9e00: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
9e10: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
9e20: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
9e30: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77  text..**.** So w
9e40: 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
9e50: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
9e60: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
9e70: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
9e80: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
9e90: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
9ea0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
9eb0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
9ec0: 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
9ed0: 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
9ee0: 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65  l..** Within the
9ef0: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
9f00: 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  er, the sqlite3_
9f10: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
9f20: 61 63 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61  ace.** can be ca
9f30: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
9f40: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
9f50: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
9f60: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
9f70: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
9f80: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
9f90: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
9fa0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
9fb0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
9fc0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
9fd0: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
9fe0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
9ff0: 65 20 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20  e in changes.** 
a000: 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
a010: 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 65 79  ggers since they
a020: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
a030: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
a040: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
a050: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
a060: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
a070: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48   without.** a WH
a080: 45 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72  ERE clause by dr
a090: 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
a0a0: 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
a0b0: 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a    (This is much.
a0c0: 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ** faster than g
a0d0: 6f 69 6e 67 20 74 68 72 6f 75 67 68 20 61 6e 64  oing through and
a0e0: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
a0f0: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
a100: 6f 6d 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e  om the.** table.
a110: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
a120: 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  is optimization,
a130: 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69   the deletions i
a140: 6e 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  n.** "DELETE FRO
a150: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
a160: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
a170: 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75   will not be cou
a180: 6e 74 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 73  nted.** by the s
a190: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a1a0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
a1b0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
a1c0: 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67  nctions..** To g
a1d0: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
a1e0: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
a1f0: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
a200: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
a210: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
a220: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
a230: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
a240: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d  :.**.** {F12241}
a250: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   The [sqlite3_ch
a260: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
a270: 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74  n shall return t
a280: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
a290: 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61           row cha
a2a0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
a2b0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
a2c0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
a2d0: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45  *          or DE
a2e0: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f  LETE statement o
a2f0: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
a300: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
a310: 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
a320: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  ithin the same o
a330: 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65 72  r higher trigger
a340: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
a350: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a  o if there have.
a360: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  **          not 
a370: 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79  been any qualify
a380: 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ing row changes.
a390: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 33 7d 20  .**.** {F12243} 
a3a0: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
a3b0: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
a3c0: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
a3d0: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
a3e0: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
a3f0: 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73  shall cause subs
a400: 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
a410: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
a420: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
a430: 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c   to return zero,
a440: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
a450: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
a460: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72  umber of rows or
a470: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20  iginally in the 
a480: 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  table..**.** LIM
a490: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
a4a0: 7b 55 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {U12252} If a se
a4b0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
a4c0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
a4d0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
a4e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
a4f0: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
a500: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a510: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
a520: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
a530: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
a540: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
a550: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
a560: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
a570: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
a580: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
a590: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
a5a0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
a5b0: 64 69 66 69 65 64 20 7b 46 31 32 32 36 30 7d 0a  dified {F12260}.
a5c0: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  ***.** This func
a5d0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
a5e0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
a5f0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 0a 2a 2a  hanges caused.**
a600: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
a610: 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
a620: 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
a630: 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
a640: 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e  e.** was opened.
a650: 20 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c    The count incl
a660: 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
a670: 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65   from all trigge
a680: 72 0a 2a 2a 20 63 6f 6e 74 65 78 74 73 2e 20 20  r.** contexts.  
a690: 42 75 74 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  But the count do
a6a0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
a6b0: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 0a 2a  hanges used to.*
a6c0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c  * implement REPL
a6d0: 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  ACE constraints,
a6e0: 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
a6f0: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
a700: 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f 50 20 74 61  g,.** or DROP ta
a710: 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a  ble processing..
a720: 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 0a 2a  ** The changes.*
a730: 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73  * are counted as
a740: 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61   soon as the sta
a750: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
a760: 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
a770: 74 65 64 20 0a 2a 2a 20 28 77 68 65 6e 20 74 68  ted .** (when th
a780: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
a790: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
a7a0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
a7b0: 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] or .** [sqlite
a7c0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
a7d0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
a7e0: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
a7f0: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
a800: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a   table" without.
a810: 2a 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  ** a WHERE claus
a820: 65 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  e by dropping an
a830: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
a840: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
a850: 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72  s much.** faster
a860: 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74   than going.** t
a870: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74  hrough and delet
a880: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65  ing individual e
a890: 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65  lements from the
a8a0: 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73   table.)  Becaus
a8b0: 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74  e of.** this opt
a8c0: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63  imization, the c
a8d0: 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20  hange count for 
a8e0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
a8f0: 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a  le" will be.** z
a900: 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ero regardless o
a910: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
a920: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
a930: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  re originally in
a940: 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54   the.** table. T
a950: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74  o get an accurat
a960: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  e count of the n
a970: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65  umber of rows de
a980: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44  leted, use.** "D
a990: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
a9a0: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61   WHERE 1" instea
a9b0: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
a9c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
a9d0: 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
a9e0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ace..**.** INVAR
a9f0: 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46  IANTS:.** .** {F
aa00: 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  12261} The [sqli
aa10: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
aa20: 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  s()] returns the
aa30: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a   total number.**
aa40: 20 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77            of row
aa50: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
aa60: 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  by INSERT, UPDAT
aa70: 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45  E, and/or DELETE
aa80: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
aa90: 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73  tements on the s
aaa0: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
aab0: 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e  nnection], in an
aac0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72  y.**          tr
aad0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73  igger context, s
aae0: 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
aaf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
ab00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65  .**          cre
ab10: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ated..**.** {F12
ab20: 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20  263} Statements 
ab30: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c  of the form "DEL
ab40: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61  ETE FROM tablena
ab50: 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20  me" with no.**  
ab60: 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c          WHERE cl
ab70: 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63  ause shall not c
ab80: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
ab90: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
aba0: 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
abb0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
abc0: 5d 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ].**.** LIMITATI
abd0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
abe0: 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
abf0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
ac00: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
ac10: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
ac20: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
ac30: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
ac40: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
ac50: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
ac60: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a  en the value .**
ac70: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
ac80: 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
ac90: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
aca0: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
acb0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
acc0: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
acd0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ace0: 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
acf0: 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20  g-Running Query 
ad00: 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12270}.**.** T
ad10: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
ad20: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
ad30: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
ad40: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
ad50: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
ad60: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
ad70: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
ad80: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
ad90: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
ada0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
adb0: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
adc0: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
add0: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
ade0: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
adf0: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
ae00: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
ae10: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
ae20: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
ae30: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
ae40: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
ae50: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
ae60: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
ae70: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
ae80: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
ae90: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
aea0: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
aeb0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
aec0: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
aed0: 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  e with a databas
aee0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
aef0: 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
af00: 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
af10: 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
af20: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
af30: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51  ..**.** If an SQ
af40: 4c 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  L is very nearly
af50: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
af60: 20 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 74   time when sqlit
af70: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a 2a  e3_interrupt().*
af80: 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  * is called, the
af90: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
afa0: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
afb0: 74 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ty to be interru
afc0: 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 68  pted..** It migh
afd0: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
afe0: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20  mpletion..** An 
aff0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
b000: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
b010: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  d will return.**
b020: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
b030: 50 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e 74  PT].  If the int
b040: 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
b050: 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20  ration is an.** 
b060: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
b070: 6f 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 69  or DELETE that i
b080: 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
b090: 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
b0a0: 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 65  , .** then the e
b0b0: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
b0c0: 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  n will be rolled
b0d0: 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
b0e0: 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  lly..** A call t
b0f0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
b100: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
b110: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
b120: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
b130: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
b140: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
b150: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
b160: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
b170: 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 68  *.** {F12271} Th
b180: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
b190: 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63  rupt()] interfac
b1a0: 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c  e will force all
b1b0: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20   running.**     
b1c0: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
b1d0: 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
b1e0: 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
b1f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b200: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
b210: 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65  halt after proce
b220: 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e  ssing at most on
b230: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77  e additional row
b240: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
b250: 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  data..**.** {F12
b260: 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61  272} Any SQL sta
b270: 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69  tement that is i
b280: 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73  nterrupted by [s
b290: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
b2a0: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
b2b0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
b2c0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
b2d0: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
b2e0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39  S:.**.** {U12279
b2f0: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
b300: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
b310: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
b320: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
b330: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72  **          is r
b340: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
b350: 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
b360: 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
b370: 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
b380: 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
b390: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b3a0: 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
b3b0: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
b3c0: 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35  s Complete {F105
b3d0: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  10}.**.** These 
b3e0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
b3f0: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
b400: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
b410: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
b420: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
b430: 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
b440: 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20  o form complete 
b450: 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
b460: 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
b470: 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
b480: 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
b490: 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
b4a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
b4b0: 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
b4c0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
b4d0: 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74  rue if the input
b4e0: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
b4f0: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
b500: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
b510: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
b520: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
b530: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
b540: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
b550: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
b560: 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d  d is not a fragm
b570: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41  ent of a.** CREA
b580: 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
b590: 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
b5a0: 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
b5b0: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
b5c0: 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
b5d0: 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
b5e0: 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
b5f0: 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
b600: 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
b610: 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
b620: 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
b630: 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
b640: 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
b650: 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
b660: 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
b670: 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  nt terminator..*
b680: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
b690: 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
b6a0: 20 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20   the SQL and.** 
b6b0: 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  so will not dete
b6c0: 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
b6d0: 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
b6e0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
b6f0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d  :.**.** {F10511}
b700: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
b710: 70 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69  plete() and sqli
b720: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
b730: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20   functions.**   
b740: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 74 72         return tr
b750: 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
b760: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
b770: 20 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20   last.**        
b780: 20 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65    non-whitespace
b790: 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20   token in their 
b7a0: 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63  input is a semic
b7b0: 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 20  olon that.**    
b7c0: 20 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e 20        is not in 
b7d0: 62 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 49  between the BEGI
b7e0: 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43  N and END of a C
b7f0: 52 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a 2a  REATE TRIGGER.**
b800: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
b810: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ent..**.** LIMIT
b820: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
b830: 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74  10512} The input
b840: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
b850: 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65 20 61  lete() must be a
b860: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
b880: 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
b890: 20 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e   {U10513} The in
b8a0: 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  put to sqlite3_c
b8b0: 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74  omplete16() must
b8c0: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
b8d0: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
b8e0: 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
b8f0: 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
b900: 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
b910: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
b920: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
b930: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
b940: 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
b950: 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
b960: 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
b970: 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
b980: 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
b990: 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33  USY Errors {F123
b9a0: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10}.**.** This r
b9b0: 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65  outine identifie
b9c0: 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
b9d0: 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
b9e0: 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77   be.** invoked w
b9f0: 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d  henever an attem
ba00: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
ba10: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
ba20: 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f  ble .** that ano
ba30: 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70  ther thread or p
ba40: 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
ba50: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  d..** If the bus
ba60: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
ba70: 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
ba80: 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
ba90: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
baa0: 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
bab0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
bac0: 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
bad0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66   the lock..** If
bae0: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
baf0: 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ck is not NULL, 
bb00: 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  then the.** call
bb10: 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
bb20: 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
bb30: 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a  guments.  The.**
bb40: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
bb50: 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69  to the handler i
bb60: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
bb70: 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
bb80: 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
bb90: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
bba0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54  this routine.  T
bbb0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
bbc0: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
bbd0: 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  dler is the numb
bbe0: 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
bbf0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
bc00: 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
bc10: 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
bc20: 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 20  ocking event.   
bc30: 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
bc40: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
bc50: 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
bc60: 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
bc70: 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
bc80: 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
bc90: 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
bca0: 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
bcb0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
bcc0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
bcd0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
bce0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
bcf0: 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
bd00: 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
bd10: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
bd20: 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
bd30: 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
bd40: 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
bd50: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
bd60: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
bd70: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
bd80: 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20  that.** it will 
bd90: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  be invoked when 
bda0: 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
bdb0: 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20  ntention..** If 
bdc0: 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
bdd0: 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
bde0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
bdf0: 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
be00: 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20  .** a deadlock, 
be10: 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
be20: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
be30: 49 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20  ITE_BUSY] or.** 
be40: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
be50: 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
be60: 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a  f invoking the.*
be70: 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
be80: 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
be90: 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
bea0: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
beb0: 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
bec0: 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
bed0: 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
bee0: 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
bef0: 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
bf00: 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
bf10: 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
bf20: 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
bf30: 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
bf40: 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
bf50: 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
bf60: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
bf70: 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
bf80: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
bf90: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
bfa0: 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
bfb0: 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
bfc0: 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
bfd0: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
bfe0: 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
bff0: 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
c000: 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
c010: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
c020: 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
c030: 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
c040: 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
c050: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
c060: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
c070: 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
c080: 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
c090: 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
c0a0: 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
c0b0: 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
c0c0: 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
c0d0: 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
c0e0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
c0f0: 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
c100: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
c110: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
c120: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
c130: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
c140: 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
c150: 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
c160: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
c170: 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
c180: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
c190: 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
c1a0: 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
c1b0: 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
c1c0: 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
c1d0: 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
c1e0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
c1f0: 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
c200: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
c210: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
c220: 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
c230: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
c240: 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
c250: 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
c260: 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
c270: 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
c280: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
c290: 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
c2a0: 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
c2b0: 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
c2c0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
c2d0: 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
c2e0: 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
c2f0: 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
c300: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
c310: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
c320: 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
c330: 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
c340: 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
c350: 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
c360: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
c370: 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
c380: 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
c390: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
c3a0: 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
c3b0: 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
c3c0: 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
c3d0: 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
c3e0: 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
c3f0: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70  ** <a href="http
c400: 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72  ://www.sqlite.or
c410: 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70  g/cvstrac/wiki?p
c420: 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f  =CorruptionFollo
c430: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a  wingBusyError">.
c440: 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ** CorruptionFol
c450: 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c  lowingBusyError<
c460: 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f  /a> wiki page fo
c470: 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f  r a discussion o
c480: 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73  f why.** this is
c490: 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a   important..**..
c4a0: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c  ** There can onl
c4b0: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
c4c0: 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
c4d0: 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ed for each data
c4e0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
c4f0: 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  on.  Setting a n
c500: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
c510: 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69  clears any previ
c520: 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74  ous one. .** Not
c530: 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
c540: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
c550: 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73  eout()] will als
c560: 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a  o set or clear.*
c570: 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
c580: 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  er..**.** INVARI
c590: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
c5a0: 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
c5b0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
c5c0: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  ] function repla
c5d0: 63 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e  ces the busy han
c5e0: 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  dler.**         
c5f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
c600: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c610: 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20  tion identified 
c620: 62 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 20  by the 1st.**   
c630: 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
c640: 20 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 79   with a new busy
c650: 20 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 66   handler identif
c660: 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 61  ied by the 2nd a
c670: 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 20  nd 3rd.**       
c680: 20 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a     parameters..*
c690: 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 68  *.** {F12312} Th
c6a0: 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 68  e default busy h
c6b0: 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 64  andler for new d
c6c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c6d0: 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ons is NULL..**.
c6e0: 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 6e  ** {F12314} When
c6f0: 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74   two or more dat
c700: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c710: 20 73 68 61 72 65 20 61 20 5b 73 71 6c 69 74 65   share a [sqlite
c720: 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
c730: 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63  cache | common c
c740: 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  ache],.**       
c750: 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64     the busy hand
c760: 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  ler for the data
c770: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c780: 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a  currently using.
c790: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
c7a0: 63 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 64  cache is invoked
c7b0: 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
c7c0: 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
c7d0: 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36  k..**.** {F12316
c7e0: 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
c7f0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
c800: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
c810: 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20  the SQLite.**   
c820: 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
c830: 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
c840: 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
c850: 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
c860: 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
c870: 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _BUSY]..**.** {F
c880: 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 69  12318} SQLite wi
c890: 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62  ll invokes the b
c8a0: 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68  usy handler with
c8b0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77   two arguments w
c8c0: 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
c8d0: 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74   are a copy of t
c8e0: 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c  he pointer suppl
c8f0: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
c900: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
c910: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
c920: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
c930: 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20   and a count of 
c940: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72  the number of pr
c950: 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
c960: 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
c970: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
c980: 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
c990: 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a  king event..**.*
c9a0: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
c9b0: 2a 0a 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20  *.** {U12319} A 
c9c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f  busy handler sho
c9d0: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f  uld not call clo
c9e0: 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
c9f0: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
ca00: 20 20 20 20 20 20 20 6f 72 20 70 72 65 70 61 72         or prepar
ca10: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ed statement tha
ca20: 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
ca30: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
ca40: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
ca50: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
ca60: 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
ca70: 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
ca80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
ca90: 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
caa0: 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F12340}.**.** 
cab0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
cac0: 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
cad0: 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
cae0: 20 68 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68 61   handler].** tha
caf0: 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77  t sleeps for a w
cb00: 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74  hile when a.** t
cb10: 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
cb20: 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c   The handler wil
cb30: 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
cb40: 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a   times until .**
cb50: 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
cb60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
cb70: 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65  leeping have bee
cb80: 6e 20 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d  n done. {F12343}
cb90: 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d   After.** "ms" m
cba0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
cbb0: 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e  leeping, the han
cbc0: 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
cbd0: 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b  hich.** causes [
cbe0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
cbf0: 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  to return [SQLIT
cc00: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
cc10: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
cc20: 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  ]..**.** Calling
cc30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
cc40: 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
cc50: 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
cc60: 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
cc70: 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
cc80: 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
cc90: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
cca0: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
ccb0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
ccc0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
ccd0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
cce0: 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
ccf0: 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65  y handler was de
cd00: 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e  fined  .** (usin
cd10: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
cd20: 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
cd30: 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
cd40: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
cd50: 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
cd60: 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
cd70: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
cd80: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34  TS:.**.** {F1234
cd90: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
cda0: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
cdb0: 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64  function overrid
cdc0: 65 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20  es any prior.** 
cdd0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
cde0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
cdf0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75  ] or [sqlite3_bu
ce00: 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65  sy_handler()] se
ce10: 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tting.**        
ce20: 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61    on the same da
ce30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ce40: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33  n..**.** {F12343
ce50: 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  } If the 2nd par
ce60: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
ce70: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
ce80: 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a  )] is less than.
ce90: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65  **          or e
cea0: 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68  qual to zero, th
ceb0: 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  en the busy hand
cec0: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 20 73  ler is cleared s
ced0: 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  o that.**       
cee0: 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e     all subsequen
cef0: 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73  t locking events
cf00: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74   immediately ret
cf10: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
cf20: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34  ]..**.** {F12344
cf30: 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  } If the 2nd par
cf40: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
cf50: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
cf60: 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65  )] is a positive
cf70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
cf80: 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75  ber N, then a bu
cf90: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65  sy handler is se
cfa0: 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c  t that repeatedl
cfb0: 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20  y calls.**      
cfc0: 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29      the xSleep()
cfd0: 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56   method in the V
cfe0: 46 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74  FS interface unt
cff0: 69 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a  il either the.**
d000: 20 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63            lock c
d010: 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74  lears or until t
d020: 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c  he cumulative sl
d030: 65 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65  eep time reporte
d040: 64 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  d back.**       
d050: 20 20 20 62 79 20 78 53 6c 65 65 70 28 29 20 65     by xSleep() e
d060: 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65  xceeds N millise
d070: 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  conds..*/.int sq
d080: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
d090: 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
d0a0: 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
d0b0: 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
d0c0: 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
d0d0: 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20  Running Queries 
d0e0: 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44  {F12370}.**.** D
d0f0: 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
d100: 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
d110: 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
d120: 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
d130: 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
d140: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
d150: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
d160: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
d170: 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
d180: 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
d190: 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
d1a0: 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
d1b0: 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
d1c0: 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
d1d0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
d1e0: 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
d1f0: 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
d200: 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
d210: 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
d220: 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
d230: 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
d240: 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
d250: 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
d260: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
d270: 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
d280: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
d290: 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
d2a0: 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
d2b0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
d2c0: 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
d2d0: 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
d2e0: 74 72 69 6e 67 73 2e 20 20 54 68 65 72 65 20 61  trings.  There a
d2f0: 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
d300: 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
d310: 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .  .** The first
d320: 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
d330: 74 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  t to zero-termin
d340: 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
d350: 74 20 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 68  t .** contain th
d360: 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
d370: 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
d380: 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
d390: 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
d3a0: 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
d3b0: 4c 4c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72 65  LL.** values are
d3c0: 20 67 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f 69   give a NULL poi
d3d0: 6e 74 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72  nter.  All other
d3e0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 0a 2a   values are in.*
d3f0: 2a 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  * their UTF-8 ze
d400: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
d410: 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
d420: 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
d430: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
d440: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
d450: 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
d460: 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
d470: 74 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ts of one or mor
d480: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
d490: 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
d4a0: 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
d4b0: 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
d4c0: 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
d4d0: 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
d4e0: 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
d4f0: 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
d500: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
d510: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
d520: 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65  ]..**.** As an e
d530: 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
d540: 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
d550: 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
d560: 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
d570: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
d580: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
d590: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
d5a0: 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
d5b0: 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
d5c0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d5d0: 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
d5e0: 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
d5f0: 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
d600: 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
d610: 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
d620: 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
d630: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
d640: 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
d650: 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
d660: 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
d670: 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
d680: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
d690: 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
d6a0: 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
d6b0: 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
d6c0: 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
d6d0: 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
d6e0: 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
d6f0: 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
d700: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
d710: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
d720: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
d730: 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
d740: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
d750: 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
d760: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d770: 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
d780: 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
d790: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
d7a0: 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
d7b0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
d7c0: 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
d7d0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d7e0: 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
d7f0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d800: 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
d810: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d820: 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
d830: 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
d840: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
d850: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
d860: 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
d870: 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
d880: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
d890: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
d8a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
d8b0: 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
d8c0: 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
d8d0: 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
d8e0: 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72  parameter.  It r
d8f0: 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
d900: 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
d910: 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
d920: 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
d930: 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
d940: 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
d950: 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
d960: 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75  d using the resu
d970: 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a  lt, it should .*
d980: 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
d990: 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
d9a0: 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
d9b0: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
d9c0: 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72  n order to .** r
d9d0: 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
d9e0: 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
d9f0: 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
da00: 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a   the way the .**
da10: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
da20: 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
da30: 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
da40: 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
da50: 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
da60: 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
da70: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
da80: 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
da90: 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69 74   Only .** [sqlit
daa0: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
dab0: 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
dac0: 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
dad0: 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
dae0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
daf0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
db00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
db10: 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
db20: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
db30: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
db40: 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
db50: 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
db60: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
db70: 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
db80: 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
db90: 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
dba0: 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
dbb0: 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
dbc0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
dbd0: 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
dbe0: 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
dbf0: 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
dc00: 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
dc10: 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
dc20: 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
dc30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
dc40: 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
dc50: 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
dc60: 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
dc70: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
dc80: 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
dc90: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
dca0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
dcb0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31  S:.**.** {F12371
dcc0: 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
dcd0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
dce0: 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
dcf0: 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
dd00: 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65           it free
dd10: 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
dd20: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
dd30: 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68  ction, aborts th
dd40: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75  e.**          qu
dd50: 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20  ery in process, 
dd60: 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71  skips any subseq
dd70: 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65  uent queries, se
dd80: 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
dd90: 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70     *resultp outp
dda0: 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55  ut pointer to NU
ddb0: 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b  LL and returns [
ddc0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
ddd0: 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66  *.** {F12373} If
dde0: 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72   the ncolumn par
ddf0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
de00: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
de10: 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
de20: 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
de30: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
de40: 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d  )] write the num
de50: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
de60: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
de70: 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
de80: 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
de90: 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71  ncolumn if the q
dea0: 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
deb0: 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
dec0: 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
ded0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
dee0: 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
def0: 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70  4} If the nrow p
df00: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
df10: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
df20: 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
df30: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
df40: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
df50: 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e  e()] write the n
df60: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
df70: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
df80: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
df90: 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
dfa0: 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79  row if the query
dfb0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
dfc0: 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74  successful (if t
dfd0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
dfe0: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a  rns SQLITE_OK)..
dff0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 54  **.** {F12376} T
e000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
e010: 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f  table()] functio
e020: 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c  n sets its *ncol
e030: 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  umn value.**    
e040: 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75 6d        to the num
e050: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
e060: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
e070: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
e080: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
e090: 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c 20   sql parameter, 
e0a0: 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68  or to zero if th
e0b0: 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68  e query in sql h
e0c0: 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 20  as an empty.**  
e0d0: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
e0e0: 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
e0f0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
e100: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
e110: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
e120: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
e130: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
e140: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
e150: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
e160: 20 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c 74   char ***pResult
e170: 2c 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  ,      /* Result
e180: 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
e190: 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20  /.  int *nrow,  
e1a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
e1b0: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
e1c0: 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
e1d0: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d  */.  int *ncolum
e1e0: 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  n,         /* Nu
e1f0: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
e200: 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
e210: 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
e220: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 2f  errmsg         /
e230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
e240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
e250: 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
e260: 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
e270: 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
e280: 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
e290: 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
e2a0: 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37  g Functions {F17
e2b0: 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
e2c0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
e2d0: 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
e2e0: 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
e2f0: 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
e300: 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
e310: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
e320: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e330: 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
e340: 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
e350: 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
e360: 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
e370: 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
e380: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
e390: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
e3a0: 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
e3b0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
e3c0: 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
e3d0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
e3e0: 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
e3f0: 66 72 65 65 28 29 5d 2e 20 20 20 42 6f 74 68 20  free()].   Both 
e400: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
e410: 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
e420: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
e430: 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
e440: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
e450: 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
e460: 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
e470: 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
e480: 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
e490: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
e4a0: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
e4b0: 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
e4c0: 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
e4d0: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
e4e0: 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
e4f0: 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
e500: 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
e510: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
e520: 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
e530: 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
e540: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
e550: 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
e560: 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
e570: 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
e580: 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
e590: 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
e5a0: 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
e5b0: 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
e5c0: 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
e5d0: 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
e5e0: 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
e5f0: 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
e600: 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
e610: 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
e620: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
e630: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
e640: 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
e650: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
e660: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
e670: 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
e680: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
e690: 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
e6a0: 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
e6b0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
e6c0: 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
e6d0: 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
e6e0: 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
e6f0: 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
e700: 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
e710: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
e720: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
e730: 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
e740: 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
e750: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
e760: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
e770: 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
e780: 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
e790: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
e7a0: 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
e7b0: 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
e7c0: 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
e7d0: 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
e7e0: 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
e7f0: 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
e800: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
e810: 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
e820: 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
e830: 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
e840: 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
e850: 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
e860: 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
e870: 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
e880: 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
e890: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
e8a0: 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
e8b0: 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
e8c0: 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
e8d0: 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
e8e0: 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
e8f0: 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
e900: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
e910: 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
e920: 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
e930: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
e940: 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
e950: 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
e960: 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
e970: 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
e980: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
e990: 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
e9a0: 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
e9b0: 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
e9c0: 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
e9d0: 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
e9e0: 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
e9f0: 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
ea00: 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
ea10: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
ea20: 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
ea30: 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
ea40: 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
ea50: 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
ea60: 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
ea70: 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
ea80: 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
ea90: 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
eaa0: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
eab0: 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
eac0: 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
ead0: 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76  so some string v
eae0: 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73  ariable contains
eaf0: 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
eb00: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
eb10: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
eb20: 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
eb30: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
eb40: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
eb50: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
eb60: 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
eb70: 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
eb80: 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
eb90: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
eba0: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
ebb0: 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
ebc0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
ebd0: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
ebe0: 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
ebf0: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
ec00: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
ec10: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
ec20: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
ec30: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
ec40: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
ec50: 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
ec60: 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
ec70: 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
ec80: 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
ec90: 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
eca0: 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
ecb0: 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
ecc0: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
ecd0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
ece0: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
ecf0: 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
ed00: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
ed10: 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
ed20: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
ed30: 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
ed40: 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
ed50: 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
ed60: 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
ed70: 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
ed80: 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
ed90: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
eda0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
edb0: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
edc0: 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
edd0: 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
ede0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
edf0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
ee00: 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
ee10: 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
ee20: 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
ee30: 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20  ral rule you.** 
ee40: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73  should always us
ee50: 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
ee60: 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
ee70: 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
ee80: 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c  ring .** literal
ee90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
eea0: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
eeb0: 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
eec0: 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
eed0: 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
eee0: 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
eef0: 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
ef00: 20 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61    Or if the para
ef10: 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67  meter in the arg
ef20: 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73  ument.** list is
ef30: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
ef40: 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
ef50: 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
ef60: 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a  (without single.
ef70: 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  ** quotes) in pl
ef80: 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
ef90: 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c  tion. {END}  So,
efa0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
efb0: 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
efc0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
efd0: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
efe0: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
eff0: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
f000: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
f010: 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
f020: 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
f030: 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
f040: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
f050: 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
f060: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
f070: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
f080: 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
f090: 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
f0a0: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
f0b0: 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
f0c0: 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
f0d0: 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
f0e0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
f0f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20  .**.** The "%z" 
f100: 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
f110: 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
f120: 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74  like "%s" with t
f130: 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
f140: 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
f150: 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
f160: 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
f170: 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
f180: 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
f190: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
f1a0: 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
f1b0: 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e  . {END}.**.** IN
f1c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
f1d0: 7b 46 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73  {F17403}  The [s
f1e0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
f1f0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  ] and [sqlite3_v
f200: 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  mprintf()] inter
f210: 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  faces.**        
f220: 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72     return either
f230: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
f240: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
f250: 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20  -8 strings held 
f260: 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  in.**           
f270: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
f280: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
f290: 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20  lloc()] or NULL 
f2a0: 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20  pointers if.**  
f2b0: 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20           a call 
f2c0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
f2d0: 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a  oc()] fails..**.
f2e0: 2a 2a 20 7b 46 31 37 34 30 36 7d 20 20 54 68 65  ** {F17406}  The
f2f0: 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
f300: 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
f310: 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65  writes a zero-te
f320: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
f330: 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
f340: 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  ng into the buff
f350: 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  er pointed to by
f360: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
f370: 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
f380: 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74     provided that
f390: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
f3a0: 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20  eter is greater 
f3b0: 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  than zero..**.**
f3c0: 20 7b 46 31 37 34 30 37 7d 20 20 54 68 65 20 5b   {F17407}  The [
f3d0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
f3e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  ()] interface do
f3f0: 65 73 20 6e 6f 74 20 77 72 69 74 65 73 20 73 6c  es not writes sl
f400: 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ots of.**       
f410: 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62      its output b
f420: 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e  uffer (the secon
f430: 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74  d parameter) out
f440: 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a  side the range.*
f450: 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30  *           of 0
f460: 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68   through N-1 (wh
f470: 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72  ere N is the fir
f480: 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
f490: 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72             regar
f4a0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e  dless of the len
f4b0: 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
f4c0: 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  g.**           r
f4d0: 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20  equested by the 
f4e0: 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61  format specifica
f4f0: 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63  tion..**   .*/.c
f500: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
f510: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
f520: 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
f530: 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
f540: 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
f550: 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
f560: 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
f570: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
f580: 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
f590: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
f5a0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
f5b0: 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a  ystem {F17300}.*
f5c0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
f5d0: 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65  core  uses these
f5e0: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
f5f0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
f600: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
f610: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f620: 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
f630: 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
f640: 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
f650: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
f660: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
f670: 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
f680: 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
f690: 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
f6a0: 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
f6b0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
f6c0: 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
f6d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
f6e0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
f6f0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
f700: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
f710: 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
f720: 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
f730: 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
f740: 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
f750: 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  eter..** If sqli
f760: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
f770: 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
f780: 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
f790: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
f7a0: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
f7b0: 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70  inter.  If the p
f7c0: 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
f7d0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f7e0: 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
f7f0: 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
f800: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
f810: 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
f820: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  inter..**.** Cal
f830: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
f840: 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
f850: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
f860: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
f870: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
f880: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f890: 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
f8a0: 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
f8b0: 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
f8c0: 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69  eused.  The sqli
f8d0: 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
f8e0: 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
f8f0: 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
f900: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
f910: 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
f920: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
f930: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
f940: 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
f950: 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
f960: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
f970: 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
f980: 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
f990: 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
f9a0: 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
f9b0: 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
f9c0: 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
f9d0: 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
f9e0: 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
f9f0: 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
fa00: 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
fa10: 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
fa20: 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
fa30: 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
fa40: 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
fa50: 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
fa60: 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
fa70: 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
fa80: 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
fa90: 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
faa0: 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
fab0: 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a  te3_free()..**.*
fac0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
fad0: 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
fae0: 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
faf0: 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
fb00: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fb10: 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
fb20: 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
fb30: 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
fb40: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
fb50: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
fb60: 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
fb70: 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
fb80: 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
fb90: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
fba0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
fbb0: 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
fbc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
fbd0: 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
fbe0: 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
fbf0: 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
fc00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
fc10: 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
fc20: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
fc30: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
fc40: 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
fc50: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
fc60: 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
fc70: 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
fc80: 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
fc90: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
fca0: 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
fcb0: 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
fcc0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
fcd0: 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
fce0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
fcf0: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
fd00: 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65 33 5f  c()..** Sqlite3_
fd10: 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
fd20: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
fd30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fd40: 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
fd50: 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
fd60: 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
fd70: 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
fd80: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
fd90: 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
fda0: 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
fdb0: 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
fdc0: 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
fdd0: 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
fde0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
fdf0: 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
fe00: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
fe10: 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
fe20: 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
fe30: 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
fe40: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
fe50: 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
fe60: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
fe70: 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
fe80: 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
fe90: 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
fea0: 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
feb0: 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
fec0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
fed0: 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
fee0: 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
fef0: 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
ff00: 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
ff10: 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
ff20: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
ff30: 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
ff40: 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
ff50: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ff60: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
ff70: 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  es the malloc(),
ff80: 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e   realloc().** an
ff90: 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
ffa0: 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
ffb0: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b 46 31  d C library. {F1
ffc0: 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
ffd0: 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  f .** SQLite is 
ffe0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fff0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72  e following C pr
10000 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
10010 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
10020 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52  te> SQLITE_MEMOR
10030 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69  Y_SIZE=<i>NNN</i
10040 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  > </blockquote>.
10050 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e 4e  **.** where <i>N
10060 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e 74  NN</i> is an int
10070 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  eger, then SQLit
10080 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
10090 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61 74  c.** array of at
100a0 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69   least <i>NNN</i
100b0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
100c0 61 6e 64 20 75 73 65 20 74 68 61 74 20 61 72 72  and use that arr
100d0 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  ay.** for all of
100e0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
100f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
10100 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
10110 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72  itional.** memor
10120 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
10130 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
10140 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
10150 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
10160 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
10170 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
10180 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
10190 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
101a0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
101b0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
101c0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
101d0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
101e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
101f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
10200 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
10210 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
10220 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
10230 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
10240 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
10250 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
10260 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  e.** used..**.**
10270 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
10280 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
10290 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
102a0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
102b0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
102c0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
102d0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
102e0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
102f0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
10300 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
10310 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
10320 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
10330 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
10340 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
10350 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
10360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10370 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
10380 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
10390 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
103a0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
103b0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
103c0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
103d0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
103e0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
103f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
10400 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b   {F17303}  The [
10410 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
10420 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10430 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
10440 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20 20 20  inter to .**    
10450 20 20 20 20 20 20 20 6e 65 77 6c 79 20 63 68 65         newly che
10460 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f  cked-out block o
10470 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
10480 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
10490 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
104a0 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
104b0 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  , .**           
104c0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
104d0 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
104e0 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68  le to fulfill th
104f0 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a  e request..**.**
10500 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b   {F17304}  The [
10510 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
10520 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10530 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
10540 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ter if.**       
10550 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68      N is less th
10560 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
10570 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ero..**.** {F173
10580 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  05}  The [sqlite
10590 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72  3_free(P)] inter
105a0 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65  face releases me
105b0 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a  mory previously.
105c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
105d0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
105e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
105f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
10600 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
10610 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61     making it ava
10620 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65  ilable for reuse
10630 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36 7d  ..**.** {F17306}
10640 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
10650 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d  ite3_free(NULL)]
10660 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
10670 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  o-op..**.** {F17
10680 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  310}  A call to 
10690 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
106a0 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61  (0,N)] is equiva
106b0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
106c0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
106d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
106e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
106f0 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  2}  A call to [s
10700 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
10710 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,0)] is equivale
10720 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
10730 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
10740 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a  lite3_free(P)]..
10750 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20  **.** {F17315}  
10760 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
10770 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61  uses [sqlite3_ma
10780 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
10790 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
107a0 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b             and [
107b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
107c0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  for all of its m
107d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
107e0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
107f0 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e    deallocation n
10800 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  eeds..**.** {F17
10810 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  318}  The [sqlit
10820 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
10830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
10840 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
10850 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
10860 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63   to a block of c
10870 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72  hecked-out memor
10880 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  y of at least N 
10890 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a  bytes in size.**
108a0 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
108b0 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
108c0 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  d, or a NULL poi
108d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  nter..**.** {F17
108e0 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  321}  When [sqli
108f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
10900 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
10910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
10920 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
10930 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66      copies the f
10940 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20  irst K bytes of 
10950 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69  content from P i
10960 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20 61 6c  nto the newly al
10970 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
10980 20 20 20 20 20 77 68 65 72 65 20 4b 20 69 73 20       where K is 
10990 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20  the lesser of N 
109a0 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
109b0 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
109c0 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20 57 68  .** {F17322}  Wh
109d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
109e0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
109f0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
10a00 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
10a10 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
10a20 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
10a30 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 33  P..**.** {F17323
10a40 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
10a50 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
10a60 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
10a70 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
10a80 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
10a90 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
10aa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
10ab0 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
10ac0 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
10ad0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
10ae0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10af0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
10b00 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
10b10 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
10b20 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
10b30 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  e a pointer obta
10b40 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
10b50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  r.**           i
10b60 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
10b70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
10b80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
10b90 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 73 0a  loc()] that has.
10ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
10bb0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
10bc0 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d 20 20  **.** {U17351}  
10bd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10be0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
10bf0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
10c00 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  of .**          
10c10 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
10c20 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
10c30 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
10c40 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10c50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10c60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
10c70 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a  alloc()]..**.*/.
10c80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
10c90 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
10ca0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
10cb0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
10cc0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
10cd0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
10ce0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
10cf0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
10d00 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a  tics {F17370}.**
10d10 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
10d20 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
10d30 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
10d40 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
10d50 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
10d60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10d70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
10d80 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
10d90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
10da0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10db0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
10dc0 69 6e 63 6c 75 64 65 64 20 77 69 74 68 69 6e 20  included within 
10dd0 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a  the SQLite..**.*
10de0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10df0 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65  .** {F17371} The
10e00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10e10 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
10e20 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
10e30 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
10e40 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  of bytes of memo
10e50 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
10e60 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20 20 20  standing .**    
10e70 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65 64 20        (malloced 
10e80 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
10e90 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54  **.** {F17373} T
10ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
10eb0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
10ec0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10ed0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
10ee0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
10ef0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10f00 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20 20 20  _used()] .**    
10f10 20 20 20 20 20 20 73 69 6e 63 65 20 74 68 65 20        since the 
10f20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
10f30 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
10f40 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20 54  **.** {F17374} T
10f50 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
10f60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
10f70 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
10f80 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
10f90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
10fa0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
10fb0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
10fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
10fd0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
10fe0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
10ff0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
11000 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
11010 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
11020 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
11030 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
11040 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
11050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
11060 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
11070 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
11080 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20 7b  y call..** .** {
11090 46 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f  F17375} The memo
110a0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
110b0 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
110c0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
110d0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
110e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
110f0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
11100 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
11110 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
11120 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
11130 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
11140 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76   is true.  The v
11150 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
11160 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [sq
11170 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
11180 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
11190 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
111a0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  k.**          pr
111b0 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
111c0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
111d0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
111e0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
111f0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
11200 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
11210 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
11220 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
11230 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
11240 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
11250 61 74 6f 72 20 7b 46 31 37 33 39 30 7d 0a 2a 2a  ator {F17390}.**
11260 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
11270 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
11280 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
11290 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
112a0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
112b0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
112c0 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e  m ROWIDs when in
112d0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
112e0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
112f0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
11300 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
11310 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44  t possible ROWID
11320 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
11330 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
11340 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
11350 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
11360 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
11370 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
11380 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
11390 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
113a0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
113b0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
113c0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  urposes..**.** A
113d0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
113e0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
113f0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
11400 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
11410 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
11420 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
11430 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
11440 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
11450 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
11460 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
11470 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
11480 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
11490 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
114a0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
114b0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
114c0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
114d0 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
114e0 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
114f0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
11500 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
11510 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
11520 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
11530 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
11540 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
11550 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
11560 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
11570 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11580 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 39 32  S:.**.** {F17392
11590 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
115a0 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20  andomness(N,P)] 
115b0 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73  interface writes
115c0 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20   N bytes of.**  
115d0 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61          high-qua
115e0 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
115f0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
11600 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  er P..*/.void sq
11610 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
11620 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
11630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11640 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
11650 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
11660 6c 6c 62 61 63 6b 73 20 7b 46 31 32 35 30 30 7d  llbacks {F12500}
11670 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
11680 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
11690 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
116a0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
116b0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
116c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
116d0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
116e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
116f0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
11700 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
11710 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
11720 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
11730 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
11740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11750 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
11760 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
11770 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
11780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11790 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
117a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
117b0 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
117c0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
117d0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
117e0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
117f0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
11800 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
11810 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
11820 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
11830 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
11840 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
11850 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
11860 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
11870 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11880 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
11890 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
118a0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
118b0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
118c0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
118d0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
118e0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
118f0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
11900 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
11910 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
11920 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
11930 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
11940 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
11950 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
11960 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
11970 20 61 6e 20 65 72 72 6f 72 2e 20 20 20 49 66 20   an error.   If 
11980 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
11990 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
119a0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
119b0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
119c0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
119d0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
119e0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b  _DENY].** then [
119f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
11a00 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
11a10 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
11a20 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
11a30 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
11a40 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
11a50 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
11a60 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
11a70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
11a80 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
11a90 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
11aa0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
11ab0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
11ac0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
11ad0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
11ae0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
11af0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11b00 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
11b10 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
11b20 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
11b30 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
11b40 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
11b50 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
11b60 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
11b70 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
11b80 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
11b90 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
11ba0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
11bb0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
11bc0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
11bd0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
11be0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
11bf0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
11c00 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
11c10 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
11c20 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
11c30 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
11c40 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
11c50 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
11c60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
11c70 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
11c80 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
11c90 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
11ca0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
11cb0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
11cc0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
11cd0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
11ce0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
11cf0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
11d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
11d10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
11d20 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
11d30 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70  f.** the third p
11d40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
11d50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
11d60 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
11d70 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ce..** The secon
11d80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
11d90 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
11da0 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53  n integer .** [S
11db0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
11dc0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
11dd0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
11de0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
11df0 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  * to be authoriz
11e00 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
11e10 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70  rough sixth.** p
11e20 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
11e30 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
11e40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
11e50 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
11e60 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  in .** additiona
11e70 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
11e80 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
11e90 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
11ea0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
11eb0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
11ec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
11ed0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
11ee0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
11ef0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a  om an untrusted.
11f00 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ** source, to en
11f10 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
11f20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20  L statements do 
11f30 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
11f40 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74  s data.** that t
11f50 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
11f60 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
11f70 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  hat they do not 
11f80 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74  try to.** execut
11f90 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
11fa0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
11fb0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
11fc0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
11fd0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
11fe0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
11ff0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
12000 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
12010 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
12020 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
12030 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
12040 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
12050 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
12060 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
12070 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
12080 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
12090 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
120a0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
120b0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
120c0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
120d0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
120e0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
120f0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
12100 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
12110 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
12120 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
12130 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
12140 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
12150 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
12160 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
12170 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
12180 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
12190 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
121a0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
121b0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
121c0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
121d0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
121e0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
121f0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
12200 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
12210 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
12220 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
12230 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  zer..**.** Only 
12240 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
12250 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
12260 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
12270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
12280 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
12290 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
122a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
122b0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
122c0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
122d0 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74   Disable the aut
122e0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
122f0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
12300 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
12310 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
12320 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12330 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
12340 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
12350 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
12360 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20  ked only during 
12370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
12380 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
12390 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
123a0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
123b0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
123c0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
123d0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
123e0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
123f0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
12400 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68  *.** {F12501} Th
12410 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
12420 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
12430 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
12440 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
12450 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
12460 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
12470 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12480 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30   D..**.** {F1250
12490 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
124a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
124b0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
124c0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
124d0 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f          being co
124e0 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31  mpiled.**.** {F1
124f0 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74  2503} If the aut
12500 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12510 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c   returns any val
12520 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
12530 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
12540 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
12550 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
12560 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a  TE_DENY] then.**
12570 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
12580 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
12590 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
125a0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75  nt call that cau
125b0 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sed.**          
125c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
125d0 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73  allback to run s
125e0 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  hall fail with a
125f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
12600 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72  QLITE_ERROR] err
12610 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61  or code and an a
12620 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
12630 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
12640 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68  {F12504} When th
12650 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
12660 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
12670 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f  QLITE_OK], the o
12680 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  peration.**     
12690 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69       described i
126a0 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c 79  s coded normally
126b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d  ..**.** {F12505}
126c0 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72   When the author
126d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
126e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
126f0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20  NY], the.**     
12700 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
12710 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
12720 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
12730 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a  hat caused the.*
12740 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
12750 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74  rizer callback t
12760 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c  o run shall fail
12770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
12780 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  h an [SQLITE_ERR
12790 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  OR] error code a
127a0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
127b0 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  age.**          
127c0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20  explaining that 
127d0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
127e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d  ..**.** {F12506}
127f0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
12800 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
12810 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
12820 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
12830 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
12840 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  k) is [SQLITE_RE
12850 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68  AD] and the auth
12860 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12870 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
12880 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f      [SQLITE_IGNO
12890 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72 65  RE] then the pre
128a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
128b0 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
128c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  o.**          in
128d0 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75  sert a NULL valu
128e0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
128f0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
12900 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
12910 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20  *          been 
12920 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
12930 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
12940 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  urned..**.** {F1
12950 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75 74  2507} If the aut
12960 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
12970 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
12980 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
12990 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
129a0 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68  llback) is anyth
129b0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
129c0 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68  SQLITE_READ], th
129d0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  en.**          a
129e0 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49   return of [SQLI
129f0 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74  TE_IGNORE] has t
12a00 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61  he same effect a
12a10 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e  s [SQLITE_DENY].
12a20 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d   .**.** {F12510}
12a30 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
12a40 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
12a50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12a60 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
12a70 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68 69           the thi
12a80 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
12a90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
12aa0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
12ab0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
12ac0 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73 65 63  {F12511} The sec
12ad0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
12ae0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
12af0 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20   an integer .** 
12b00 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
12b10 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
12b20 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
12b30 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
12b40 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  ar action.**    
12b50 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74 68        to be auth
12b60 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
12b70 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72 64  12512} The third
12b80 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
12b90 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
12ba0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a   callback are.**
12bb0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
12bc0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
12bd0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a  s that contain .
12be0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69  **          addi
12bf0 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
12c00 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
12c10 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
12c20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d  ..**.** {F12520}
12c30 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
12c40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
12c50 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64  rizer()] overrid
12c60 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
12c70 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
12c80 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
12c90 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orizer..**.** {F
12ca0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
12cb0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
12cc0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
12cd0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
12ce0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
12cf0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
12d00 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
12d10 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
12d20 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
12d30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12d40 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
12d50 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
12d60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
12d70 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
12d80 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
12d90 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
12da0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
12db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12dc0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
12dd0 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30  rn Codes {F12590
12de0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  }.**.** The [sql
12df0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
12e00 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
12e10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
12e20 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
12e30 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
12e40 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
12e50 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
12e60 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
12e70 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
12e80 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
12e90 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
12ea0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
12eb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
12ec0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
12ed0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
12ee0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
12ef0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
12f00 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69  mation..*/.#defi
12f10 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
12f20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
12f30 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
12f40 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
12f50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12f60 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
12f70 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
12f80 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
12f90 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
12fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12fb0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
12fc0 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35  ion Codes {F1255
12fd0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0}.**.** The [sq
12fe0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
12ff0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
13000 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
13010 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
13020 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
13030 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72  ed to authorizer
13040 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
13050 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
13060 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
13070 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
13080 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
13090 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
130a0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
130b0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
130c0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
130d0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
130e0 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
130f0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
13100 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
13110 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
13120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
13130 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
13140 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
13150 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
13160 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74  is to be .** aut
13170 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
13180 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
13190 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
131a0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
131b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
131c0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
131d0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
131e0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
131f0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
13200 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
13210 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
13220 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
13230 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
13240 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13250 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
13260 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
13270 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a  ain", "temp", .*
13280 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
13290 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20  cable.  The 6th 
132a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
132b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
132c0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
132d0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
132e0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
132f0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
13300 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
13310 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
13320 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
13330 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
13340 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
13350 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  rom .** top-leve
13360 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  l SQL code..**.*
13370 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
13380 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 54 68 65  .** {F12551} The
13390 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
133a0 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20 20  r to an .**     
133b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
133c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
133d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
133e0 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61 6e  ck] is always an
133f0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
13400 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
13410 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
13420 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
13430 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a  ies what action.
13440 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62  **          is b
13450 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
13460 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 7d 20  .**.** {F12552} 
13470 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
13480 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
13490 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  e .**          [
134a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
134b0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
134c0 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  zation callback 
134d0 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20  function].**    
134e0 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61        will be pa
134f0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
13500 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
13510 69 63 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ich .**         
13520 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
13530 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
13540 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
13550 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13560 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d  ..**.** {F12553}
13570 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
13580 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
13590 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
135a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
135b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
135c0 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
135d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
135e0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78  the database (ex
135f0 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22  ample: "main", "
13600 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20  temp", etc.) if 
13610 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a  applicable..**.*
13620 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36  * {F12554} The 6
13630 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
13640 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
13650 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
13660 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
13670 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
13680 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
13690 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
136a0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
136b0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
136c0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
136d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
136e0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
136f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
13700 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
13710 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  s directly from 
13720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70  .**          top
13730 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
13740 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
13750 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13760 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13770 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
13780 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
13790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
137a0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
137b0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
137c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
137d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
137e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
137f0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
13800 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
13810 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
13820 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13840 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
13850 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
13860 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
13870 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
13880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13890 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
138a0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
138b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
138c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
138d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
138e0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
138f0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
13900 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
13910 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
13920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
13930 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
13940 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
13950 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
13960 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13970 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
13980 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
13990 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
139a0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
139b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
139c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
139d0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
139e0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
139f0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
13a00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13a10 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
13a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
13a30 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
13a40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
13a50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13a60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
13a70 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
13a80 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
13a90 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
13aa0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13ab0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
13ac0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
13ad0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
13ae0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13af0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13b00 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
13b10 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
13b20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
13b30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
13b40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13b50 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
13b60 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
13b70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13b80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13b90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13ba0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
13bb0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
13bc0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
13bd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
13be0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13bf0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
13c00 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
13c10 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
13c20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13c30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13c40 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
13c50 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
13c60 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
13c70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13c90 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
13ca0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
13cb0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
13cc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13cd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13ce0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
13cf0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
13d00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
13d10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13d20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13d30 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
13d40 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
13d50 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
13d60 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
13d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
13d80 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
13d90 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
13da0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
13db0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
13dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
13dd0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
13de0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
13df0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
13e00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
13e20 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
13e30 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    22   /* NULL  
13e40 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
13e50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
13e70 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
13e80 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
13e90 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
13ea0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
13eb0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
13ec0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
13ed0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
13ee0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
13ef0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13f00 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
13f10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
13f20 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
13f30 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
13f40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13f50 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
13f60 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
13f70 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
13f80 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
13f90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13fa0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
13fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
13fc0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
13fd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13fe0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13ff0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
14000 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
14010 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
14020 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
14030 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
14040 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
14050 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
14060 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
14070 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
14080 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
14090 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
140a0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
140b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
140c0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
140d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
140e0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
140f0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
14100 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
14110 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
14120 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14130 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
14140 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
14150 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
14160 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
14170 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
14180 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
14190 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a  ns {F12280}.**.*
141a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
141b0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
141c0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
141d0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
141e0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
141f0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
14200 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
14210 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
14220 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
14230 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
14240 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
14250 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
14260 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
14270 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
14280 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
14290 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
142a0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
142b0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  The callback ret
142c0 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e  urns a UTF-8 ren
142d0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51  dering of the SQ
142e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
142f0 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65  .** as the state
14300 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
14310 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64  s executing.  Ad
14320 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63  ditional callbac
14330 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ks occur.** as e
14340 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
14350 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
14360 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
14370 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
14380 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
14390 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
143a0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
143b0 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  the trigger..** 
143c0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
143d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
143e0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
143f0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
14400 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
14410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
14420 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f  nishes.  The pro
14430 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
14440 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
14450 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
14460 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
14470 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
14480 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
14490 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
144a0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
144b0 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  un..**.** The sq
144c0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
144d0 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79  API is currently
144e0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
144f0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20  rimental and.** 
14500 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
14510 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20  ange or removal 
14520 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
14530 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ase..**.** The t
14540 72 69 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67  rigger reporting
14550 20 66 65 61 74 75 72 65 20 6f 66 20 74 68 65 20   feature of the 
14560 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
14570 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  s considered.** 
14580 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
14590 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
145a0 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c  hange or removal
145b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
145c0 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76  ses..** Future v
145d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
145e0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
145f0 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62   new trace callb
14600 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  ack .** invocati
14610 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ons..**.** INVAR
14620 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
14630 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61  2281} The callba
14640 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
14650 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
14660 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73 0a 2a  e3_trace()] is.*
14670 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65  *          whene
14680 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ver an SQL state
14690 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
146a0 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64  s to execute and
146b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
146c0 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20  never a trigger 
146d0 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74  subprogram first
146e0 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a   begins to run..
146f0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45  **.** {F12282} E
14700 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
14710 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 76  ite3_trace()] ov
14720 65 72 72 69 64 65 73 20 74 68 65 20 70 72 65 76  errides the prev
14730 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
14740 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 72     registered tr
14750 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ace callback..**
14760 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20 41 20 4e  .** {F12283} A N
14770 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61  ULL trace callba
14780 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72 61 63  ck disables trac
14790 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ing..**.** {F122
147a0 38 34 7d 20 54 68 65 20 66 69 72 73 74 20 61 72  84} The first ar
147b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
147c0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
147d0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
147e0 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65        the pointe
147f0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
14800 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
14810 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
14820 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35  ]..**.** {F12285
14830 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  } The second arg
14840 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
14850 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ce callback is a
14860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
14870 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14880 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
14890 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
148a0 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   text.**        
148b0 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61    of the SQL sta
148c0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
148d0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71   passed into [sq
148e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
148f0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
14900 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
14910 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  t, or an SQL com
14920 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20  ment indicating 
14930 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  the beginning.**
14940 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74            of a t
14950 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
14960 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37  m..**.** {F12287
14970 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
14980 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
14990 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
149a0 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76  rofile()] is inv
149b0 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
149c0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
149d0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
149e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20  .**.** {F12288} 
149f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
14a00 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
14a10 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
14a20 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
14a30 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72       the 3rd par
14a40 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
14a50 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a  e3_profile()]..*
14a60 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54 68  *.** {F12289} Th
14a70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14a80 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
14a90 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
14aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
14ab0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
14ac0 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f  8 string that co
14ad0 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c  ntains the compl
14ae0 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20  ete text of.**  
14af0 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20          the SQL 
14b00 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20  statement as it 
14b10 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79  was processed by
14b20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14b30 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
14b40 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
14b50 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alent..**.** {F1
14b60 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20  2290} The third 
14b70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14b80 20 70 72 6f 66 69 6c 65 20 20 63 61 6c 6c 62 61   profile  callba
14b90 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ck is an estimat
14ba0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
14bb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
14bc0 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61  anoseconds of wa
14bd0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65  ll-clock time re
14be0 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20  quired to.**    
14bf0 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51        run the SQ
14c00 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d  L statement from
14c10 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68   start to finish
14c20 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
14c30 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
14c40 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
14c50 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
14c60 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  r*), void*);.voi
14c70 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
14c80 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
14c90 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
14ca0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
14cb0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
14cc0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
14cd0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
14ce0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
14cf0 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a  acks {F12910}.**
14d00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
14d10 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
14d20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
14d30 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
14d40 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
14d50 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
14d60 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
14d70 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
14d80 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
14d90 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
14da0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
14db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
14dc0 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20 41 6e 20  _table()].   An 
14dd0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
14de0 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61  this .** interfa
14df0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
14e00 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
14e10 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
14e20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
14e30 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
14e40 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
14e50 6f 2c 20 74 68 65 20 6f 70 65 72 74 69 6f 6e 20  o, the opertion 
14e60 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
14e70 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
14e80 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
14e90 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
14ea0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
14eb0 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62  n a GUI dialog b
14ec0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ox..**.** INVARI
14ed0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
14ee0 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  911} The callbac
14ef0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
14f00 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  tered by [sqlite
14f10 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
14f20 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  er()].**        
14f30 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72    is invoked per
14f40 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
14f50 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
14f60 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  lls to.**       
14f70 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
14f80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ()]..**.** {F129
14f90 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  12} The progress
14fa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14fb0 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
14fc0 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a  ery N virtual.**
14fd0 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e            machin
14fe0 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65  e opcodes, where
14ff0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
15000 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a   argument to .**
15010 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
15020 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
15030 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20  handler()] call 
15040 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a  that registered.
15050 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
15060 63 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f 64 6f  callback.  <todo
15070 3e 57 68 61 74 20 69 66 20 4e 20 69 73 20 6c 65  >What if N is le
15080 73 73 20 74 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f  ss than 1?</todo
15090 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d  >.**.** {F12913}
150a0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
150b0 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73  llback itself is
150c0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
150d0 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20  he third.**     
150e0 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f       argument to
150f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
15100 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a  ss_handler()]..*
15110 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20 54 68  *.** {F12914} Th
15120 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
15130 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  t [sqlite3_progr
15140 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 69  ess_handler()] i
15150 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20  s a.***         
15160 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73  void pointer pas
15170 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72  sed to the progr
15180 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ess callback.** 
15190 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
151a0 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69  n each time it i
151b0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
151c0 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61 20 63   {F12915} If a c
151d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
151e0 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20  step()] results 
151f0 69 6e 20 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a  in fewer than.**
15200 20 20 20 20 20 20 20 20 20 20 4e 20 6f 70 63 6f            N opco
15210 64 65 73 20 62 65 69 6e 67 20 65 78 65 63 75 74  des being execut
15220 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
15230 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
15240 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  s callback is ne
15250 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e  ver invoked. {EN
15260 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31  D}.** .** {F1291
15270 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f  6} Every call to
15280 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
15290 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a  ss_handler()].**
152a0 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72            overwr
152b0 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75  ites any previou
152c0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 70  sly registered p
152d0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
152e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20  .**.** {F12917} 
152f0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
15300 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
15310 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f   is NULL then no
15320 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20   progress.**    
15330 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73        handler is
15340 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
15350 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65 20  {F12918} If the 
15360 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
15370 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  k returns a resu
15380 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c  lt other than 0,
15390 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
153a0 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69    the behavior i
153b0 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  s a if [sqlite3_
153c0 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61 64  interrupt()] had
153d0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f   been called..*/
153e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
153f0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
15400 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
15410 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
15420 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
15430 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
15440 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
15450 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d  nection {F12700}
15460 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
15470 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
15480 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
15490 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a  le whose name.**
154a0 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
154b0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
154c0 6e 74 2e 0a 2a 2a 20 54 68 65 20 66 69 6c 65 6e  nt..** The filen
154d0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
154e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
154f0 54 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c  TF-8.** for [sql
15500 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
15510 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
15520 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
15530 31 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  16.** in the nat
15540 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
15550 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15560 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71  16()]..** An [sq
15570 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69  lite3*] handle i
15580 73 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e  s usually return
15590 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
155a0 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72  n.** if an error
155b0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
155c0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
155d0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
155e0 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61  ble.** to alloca
155f0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
15600 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
15610 6f 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c 20 77  object, a NULL w
15620 69 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74 74 65  ill.** be writte
15630 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
15640 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
15650 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
15660 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49 66  3] object..** If
15670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
15680 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
15690 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 63 63  created).** succ
156a0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20 5b  essfully, then [
156b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
156c0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
156d0 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  se an.** error c
156e0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
156f0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
15700 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
15710 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
15720 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61  ()]  routines ca
15730 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
15740 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
15750 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
15760 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
15770 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ror..**.** The d
15780 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
15790 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
157a0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
157b0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  f.** [sqlite3_op
157c0 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
157d0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
157e0 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
157f0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
15800 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
15810 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
15820 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ()] is used..**.
15830 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
15840 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
15850 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
15860 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
15870 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
15880 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  h the [sqlite3*]
15890 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
158a0 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70 61  e released by pa
158b0 73 73 69 6e 67 20 69 74 0a 2a 2a 20 74 6f 20 5b  ssing it.** to [
158c0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
158d0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
158e0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
158f0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
15900 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
15910 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
15920 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ke [sqlite3_open
15930 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20 74  ()] .** except t
15940 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
15950 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
15960 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
15970 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
15980 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
15990 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
159a0 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20  ion.  The flags 
159b0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
159c0 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a  .** one of:.**.*
159d0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ol>.** <li>  
159e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
159f0 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  DONLY].** <li>  
15a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
15a10 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  DWRITE].** <li> 
15a20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
15a30 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
15a40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a  TE_OPEN_CREATE].
15a50 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ol>.**.** T
15a60 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f  he first value o
15a70 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
15a80 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a  e read-only. .**
15a90 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
15aa0 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 76 69 6f   does not previo
15ab0 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
15ac0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
15ad0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15ae0 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  option opens.** 
15af0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
15b00 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
15b10 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
15b20 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c  , or reading onl
15b30 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66  y if.** if the f
15b40 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
15b50 74 65 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68  tected.  In eith
15b60 65 72 20 63 61 73 65 20 74 68 65 20 64 61 74 61  er case the data
15b70 62 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72  base.** must alr
15b80 65 61 64 79 20 65 78 69 73 74 20 6f 72 20 61 6e  eady exist or an
15b90 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
15ba0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f  ed.  The third o
15bb0 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74  ption.** opens t
15bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
15bd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
15be0 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65 73 20  ing and creates 
15bf0 69 74 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a  it if it does.**
15c00 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
15c10 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  st..** The third
15c20 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61   options is beha
15c30 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
15c40 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71  ays used for [sq
15c50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
15c60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
15c70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  en16()]..**.** I
15c80 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
15c90 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
15ca0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 6e 6f  open_v2()] is no
15cb0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
15cc0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
15cd0 77 6e 20 61 62 6f 76 65 20 74 68 65 6e 20 74 68  wn above then th
15ce0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
15cf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
15d00 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
15d10 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
15d20 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a  en an private.**
15d30 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
15d40 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
15d50 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
15d60 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
15d70 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77  ry.** database w
15d80 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20  ill vanish when 
15d90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15da0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
15db0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
15dc0 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
15dd0 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65 20 6f  might make use o
15de0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
15df0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a  cial filenames.*
15e00 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  * that begin wit
15e10 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
15e20 74 65 72 2e 20 20 49 74 20 69 73 20 72 65 63 6f  ter.  It is reco
15e30 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a  mmended that .**
15e40 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
15e50 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79   filename really
15e60 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
15e70 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79 6f 75  .** ":" that you
15e80 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
15e90 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
15ea0 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74  name like "./" t
15eb0 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69 67  o.** avoid ambig
15ec0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
15ed0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
15ee0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
15ef0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20 74  then a private t
15f00 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
15f10 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
15f20 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
15f30 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
15f40 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
15f50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
15f60 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
15f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15f80 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
15f90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
15fa0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
15fb0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
15fc0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
15fd0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
15fe0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
15ff0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
16000 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
16010 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74   .** interface t
16020 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74 61  hat the new data
16030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16040 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
16050 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
16060 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c  rameter is a NUL
16070 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
16080 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
16090 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65  te3_vfs].** obje
160a0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
160b0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
160c0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
160d0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
160e0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
160f0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
16100 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  of [sqlite3_open
16110 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
16120 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74  _open_v2()] must
16130 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
16140 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
16150 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
16160 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
16170 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
16180 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
16190 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
161a0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
161b0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
161c0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
161d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  o.** [sqlite3_op
161e0 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
161f0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
16200 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
16210 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54  **.** {F12701} T
16220 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
16230 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
16240 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
16250 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
16260 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
16270 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61  erfaces create a
16280 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
16290 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
162a0 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
162b0 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
162c0 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
162d0 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68  file given in th
162e0 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65  eir first parame
162f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  ter..**.** {F127
16300 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  02} The filename
16310 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
16320 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
16330 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  8.**          fo
16340 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
16350 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
16360 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
16370 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20  s UTF-16.**     
16380 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
16390 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
163a0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
163b0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  6()]..**.** {F12
163c0 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  703} A successfu
163d0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
163e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
163f0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
16400 36 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20  6()], .**       
16410 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
16420 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73  pen_v2()] writes
16430 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16440 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
16450 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16460 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62  tion] into *ppDb
16470 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 34 7d  ..**.** {F12704}
16480 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
16490 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
164a0 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
164b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
164c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
164d0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
164e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f   [SQLITE_OK] upo
164f0 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20  n success,.**   
16500 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70         or an app
16510 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
16520 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65  code] on failure
16530 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 36 7d  ..**.** {F12706}
16540 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
16550 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
16560 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
16570 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
16580 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
16590 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
165a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
165b0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a  will be UTF-8..*
165c0 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20 54 68  *.** {F12707} Th
165d0 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65  e default text e
165e0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65  ncoding for a ne
165f0 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  w database creat
16600 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
16610 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
16620 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20  en16()] will be 
16630 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46  UTF-16..**.** {F
16640 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  12709} The [sqli
16650 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69  te3_open(F,D)] i
16660 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69  nterface is equi
16670 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  valent to.**    
16680 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
16690 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d  pen_v2(F,D,G,0)]
166a0 20 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72   where the G par
166b0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
166c0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50        [SQLITE_OP
166d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53  EN_READWRITE]|[S
166e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
166f0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  E]..**.** {F1271
16700 31 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  1} If the G para
16710 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
16720 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
16730 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
16740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
16750 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
16760 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68  PEN_READONLY] th
16770 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
16780 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
16790 20 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e        for readin
167a0 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  g only..**.** {F
167b0 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20  12712} If the G 
167c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
167d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
167e0 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
167f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
16800 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
16810 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
16820 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  E] then the data
16830 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a  base is opened.*
16840 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69  *          readi
16850 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
16860 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66  f possible, or f
16870 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
16880 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
16890 20 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65     file is write
168a0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
168b0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
168c0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  em..**.** {F1271
168d0 33 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  3} If the G para
168e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
168f0 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c  3_open(v2(F,D,G,
16900 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a  V)] omits the.**
16910 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
16920 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
16930 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65  _CREATE] and the
16940 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
16950 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ot.**          p
16960 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
16970 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
16980 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  urned..**.** {F1
16990 32 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70  2714} If the G p
169a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
169b0 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44  ite3_open(v2(F,D
169c0 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
169d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
169e0 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
169f0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
16a00 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
16a10 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
16a20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
16a30 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61  exist, then an a
16a40 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
16a50 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20  o create and.** 
16a60 20 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c           initial
16a70 69 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ize the database
16a80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d  ..**.** {F12717}
16a90 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
16aa0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
16ab0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
16ac0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
16ad0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
16ae0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
16af0 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72  v2()] is ":memor
16b00 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
16b10 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
16b20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d    ephemeral, in-
16b30 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
16b40 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
16b50 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  he connection..*
16b60 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
16b70 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >Is SQLITE_OPEN_
16b80 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50  CREATE|SQLITE_OP
16b90 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71  EN_READWRITE req
16ba0 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  uired.**        
16bb0 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65    in sqlite3_ope
16bc0 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a  n_v2()?</todo>.*
16bd0 2a 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20 49 66  *.** {F12719} If
16be0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
16bf0 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
16c00 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
16c10 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
16c20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20        ephemeral 
16c30 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
16c40 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
16c50 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
16c60 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
16c70 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
16c80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
16c90 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
16ca0 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
16cb0 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
16cc0 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 31 7d  >.**.** {F12721}
16cd0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
16ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74  onnection] creat
16cf0 65 64 20 62 79 20 0a 2a 2a 20 20 20 20 20 20 20  ed by .**       
16d00 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
16d10 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 77 69  _v2(F,D,G,V)] wi
16d20 6c 6c 20 75 73 65 20 74 68 65 0a 2a 2a 20 20 20  ll use the.**   
16d30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16d40 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e  vfs] object iden
16d50 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56 20  tified by the V 
16d60 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
16d70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 65            the de
16d80 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
16d90 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 56 20  fs] object is V 
16da0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
16db0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 33  r..**.** {F12723
16dc0 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20  } Two [database 
16dd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 64 61 74  connection | dat
16de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16df0 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20  s] will share a 
16e00 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 0a 2a 2a 20  common cache.** 
16e10 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68           if both
16e20 20 77 65 72 65 20 6f 70 65 6e 65 64 20 77 69 74   were opened wit
16e30 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 0a 2a  h the same VFS.*
16e40 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
16e50 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
16e60 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
16e70 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
16e80 65 20 77 61 73 20 65 6e 61 62 6c 65 64 5d 20 61  e was enabled] a
16e90 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
16ea0 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73  f both filenames
16eb0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75   compare equal u
16ec0 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 0a 2a 2a  sing memcmp().**
16ed0 20 20 20 20 20 20 20 20 20 20 61 66 74 65 72 20            after 
16ee0 68 61 76 69 6e 67 20 62 65 65 6e 20 70 72 6f 63  having been proc
16ef0 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73 71  essed by the [sq
16f00 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c  lite3_vfs | xFul
16f10 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f  lPathname] metho
16f20 64 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  d of.**         
16f30 20 74 68 65 20 56 46 53 2e 0a 2a 2a 0a 2a 2f 0a   the VFS..**.*/.
16f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
16f50 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
16f60 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
16f70 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
16f80 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
16f90 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
16fa0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
16fb0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
16fc0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
16fd0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
16fe0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
16ff0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
17000 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
17010 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
17020 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
17030 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
17040 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
17050 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
17060 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
17070 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
17080 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
17090 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
170a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
170b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
170c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
170d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
170e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
170f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
17100 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
17110 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
17120 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
17130 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
17140 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
17150 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
17160 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12800}.**.** Th
17170 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
17180 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
17190 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
171a0 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  c.** [SQLITE_OK 
171b0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f  | result code] o
171c0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
171d0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
171e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
171f0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
17200 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
17210 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
17220 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
17230 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c   [sqlite3] handl
17240 65 20 27 64 62 27 2e 20 49 66 20 61 20 70 72 69  e 'db'. If a pri
17250 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
17260 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f  ed but the.** mo
17270 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
17280 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
17290 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
172a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
172b0 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ode().** is unde
172c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
172d0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
172e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
172f0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
17300 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
17310 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
17320 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
17330 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
17340 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65  8 or UTF16 respe
17350 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
17360 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
17370 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
17380 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
17390 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
173a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
173b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
173c0 6f 72 72 79 20 77 69 74 68 20 66 72 65 65 69 6e  orry with freein
173d0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
173e0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
173f0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
17400 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
17410 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
17420 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
17430 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
17440 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
17450 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
17460 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
17470 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20  ** {F12801} The 
17480 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
17490 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (D)] interface r
174a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
174b0 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ic.**          [
174c0 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
174d0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20  lt code] or.**  
174e0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
174f0 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
17500 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
17510 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  e].**          f
17520 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
17530 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
17540 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63  rface call assoc
17550 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
17560 20 20 77 69 74 68 20 5b 64 61 74 61 62 61 73 65    with [database
17570 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
17580 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54  **.** {F12803} T
17590 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  he [sqlite3_errm
175a0 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69  sg(D)] and [sqli
175b0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
175c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
175d0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45  erfaces return E
175e0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
175f0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
17600 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  bes.**          
17610 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65  the error in the
17620 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79   mostly recently
17630 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
17640 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20  e call,.**      
17650 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65      encoded as e
17660 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
17670 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
17680 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d  ..**.** {F12807}
17690 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
176a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
176b0 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
176c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
176d0 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
176e0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
176f0 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65   the next SQLite
17700 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e   interface call.
17710 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20  .**.** {F12808} 
17720 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
17730 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
17740 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  t return an erro
17750 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
17760 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71     (example: [sq
17770 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
17780 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20  ()]) do not.**  
17790 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74          change t
177a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72  he error code or
177b0 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
177c0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
177d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
177e0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
177f0 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
17800 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
17810 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39  ]..**.** {F12809
17820 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
17830 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
17840 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
17850 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
17860 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17870 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
17880 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
17890 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
178a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
178b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
178c0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
178d0 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
178e0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
178f0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
17900 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
17910 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
17920 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
17930 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
17940 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
17950 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
17960 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
17970 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
17980 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
17990 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
179a0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
179b0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
179c0 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
179d0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
179e0 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  3000}.** KEYWORD
179f0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
17a00 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
17a10 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
17a20 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
17a30 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
17a40 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
17a50 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
17a60 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  .  This.** objec
17a70 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
17a80 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
17a90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
17aa0 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  r a .** "compile
17ab0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
17ac0 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
17ad0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20  "statement"..** 
17ae0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
17af0 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
17b00 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
17b10 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
17b20 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
17b30 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
17b40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
17b50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
17b60 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
17b70 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
17b80 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
17b90 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
17ba0 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ters using.**   
17bb0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
17bc0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
17bd0 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65  bind_* interface
17be0 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  s]..** <li> Run 
17bf0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
17c00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
17c10 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
17c20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
17c30 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
17c40 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
17c50 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
17c60 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
17c70 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
17c80 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
17c90 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
17ca0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
17cb0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
17cc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
17cd0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
17ce0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
17cf0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
17d00 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
17d10 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
17d20 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
17d30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
17d40 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
17d50 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
17d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
17d70 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 46  n-time Limits {F
17d80 31 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12760}.**.** Thi
17d90 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
17da0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
17db0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
17dc0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
17dd0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
17de0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
17df0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
17e00 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
17e10 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
17e20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
17e30 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
17e40 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
17e50 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
17e60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
17e70 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
17e80 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
17e90 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
17ea0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
17eb0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
17ec0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
17ed0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
17ee0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
17ef0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
17f00 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
17f10 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
17f20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  limit..**.** If 
17f30 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
17f40 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
17f50 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
17f60 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46   unchanged..** F
17f70 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
17f80 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
17f90 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
17fa0 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a  is a hard upper.
17fb0 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20  ** bound set by 
17fc0 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
17fd0 2d 70 72 65 70 72 6f 63 65 73 73 20 6d 61 63 72  -preprocess macr
17fe0 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d  o named SQLITE_M
17ff0 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20  AX_XYZ..** (The 
18000 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
18010 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
18020 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
18030 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
18040 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
18050 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
18060 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
18070 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
18080 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
18090 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
180a0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
180b0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
180c0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
180d0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
180e0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
180f0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
18100 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
18110 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
18120 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
18130 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
18140 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
18150 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
18160 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
18170 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72   a.** webbrowser
18180 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
18190 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
181a0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
181b0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
181c0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
181d0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
181e0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
181f0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
18200 66 20 74 68 65 20 69 6e 74 65 72 6e 65 74 2e 20  f the internet. 
18210 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
18220 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
18230 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
18240 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
18250 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
18260 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
18270 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
18280 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
18290 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
182a0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
182b0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
182c0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 68 2e  rvice.** attach.
182d0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
182e0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
182f0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
18300 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
18310 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
18320 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
18330 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
18340 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
18350 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
18360 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
18370 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
18380 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
18390 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
183a0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
183b0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  AGMA]..**.** Thi
183c0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  s interface is c
183d0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
183e0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
183f0 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 0a   and is subject.
18400 2a 2a 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ** to change or 
18410 72 65 6d 6f 76 61 6c 20 77 69 74 68 6f 75 74 20  removal without 
18420 70 72 69 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a  prior notice..**
18430 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
18440 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 32 7d 20 41  **.** {F12762} A
18450 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
18460 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
18470 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
18480 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   V is.**        
18490 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67    positive chang
184a0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
184b0 20 20 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20     limit on the 
184c0 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
184d0 74 20 43 20 69 6e 20 5b 64 61 74 61 62 61 73 65  t C in [database
184e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
184f0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
18500 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e  e lesser of V an
18510 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  d the hard upper
18520 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
18530 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ze.**          o
18540 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20  f C that is set 
18550 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
18560 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20  .**.** {F12766} 
18570 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
18580 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
18590 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
185a0 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a  e V is negative.
185b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76  **          leav
185c0 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20  es the state of 
185d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
185e0 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65  tion] D unchange
185f0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39  d..**.** {F12769
18600 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
18610 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
18620 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65  limit(D,C,V)] re
18630 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
18640 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
18650 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
18660 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
18670 74 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  t C in.**       
18680 20 20 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20     in [database 
18690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73  connection] D as
186a0 20 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f   it was prior to
186b0 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e   the call..*/.in
186c0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
186d0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
186e0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
186f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18700 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
18710 61 74 65 67 6f 72 69 65 73 20 7b 46 31 32 37 39  ategories {F1279
18720 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
18730 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
18740 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   {limit categori
18750 65 73 7d 0a 2a 2a 20 0a 2a 2a 20 54 68 65 73 65  es}.** .** These
18760 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
18770 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74  e various aspect
18780 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65  s of a [database
18790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
187a0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69  that can be limi
187b0 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63  ted in size by c
187c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
187d0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
187e0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
187f0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
18800 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   are as follows:
18810 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
18820 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18830 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
18840 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
18850 69 7a 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 73 74  ize of any.** st
18860 72 69 6e 67 20 6f 72 20 62 6c 6f 62 20 6f 72 20  ring or blob or 
18870 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
18880 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18890 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
188a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
188b0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
188c0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
188d0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
188e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
188f0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
18900 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18910 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
18920 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
18930 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
18940 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
18950 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74  of a SELECT or t
18960 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18970 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
18980 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
18990 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
189a0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
189b0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
189c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
189d0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
189e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
189f0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
18a00 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
18a10 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
18a20 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18a30 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
18a40 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
18a50 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18a60 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
18a70 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
18a80 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
18a90 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
18aa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
18ab0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
18ac0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
18ad0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
18ae0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
18af0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
18b00 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
18b10 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
18b20 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
18b30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18b40 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
18b50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18b60 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18b70 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
18b80 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
18b90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18ba0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
18bb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18bc0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
18bd0 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  f attached datab
18be0 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ases.</dd>.**.**
18bf0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18c00 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
18c10 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
18c20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
18c30 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
18c40 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
18c50 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47  the LIKE or.** G
18c60 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  LOB operators.</
18c70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18c80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
18c90 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
18ca0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18cb0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
18cc0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
18cd0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
18ce0 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
18cf0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
18d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18d10 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
18d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18d30 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
18d40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
18d50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
18d60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
18d70 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
18d80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18d90 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
18da0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
18db0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
18dc0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
18dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
18de0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
18df0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
18e00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
18e10 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
18e20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
18e30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
18e40 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
18e50 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
18e60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
18e70 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
18e80 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
18e90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
18ea0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
18eb0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
18ec0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18ed0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
18ee0 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
18ef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
18f00 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
18f10 61 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d  atement {F13010}
18f20 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
18f30 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
18f40 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
18f50 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
18f60 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
18f70 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
18f80 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
18f90 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  s. .**.** The fi
18fa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62  rst argument "db
18fb0 22 20 69 73 20 61 6e 20 5b 64 61 74 61 62 61 73  " is an [databas
18fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a  e connection] .*
18fd0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
18fe0 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
18ff0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
19000 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
19010 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  v2()].** or [sql
19020 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
19030 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
19040 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69  rgument "zSql" i
19050 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
19060 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
19070 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
19080 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
19090 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
190a0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
190b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
190c0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
190d0 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61  ces uses UTF-8 a
190e0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
190f0 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
19100 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19110 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
19120 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
19130 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
19140 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68  nt is less.** th
19150 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
19160 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
19170 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
19180 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
19190 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
191a0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
191b0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
191c0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79  number of .** by
191d0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
191e0 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
191f0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
19200 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
19210 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
19220 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
19230 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
19240 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a  character or .**
19250 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
19260 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
19270 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
19280 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
19290 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
192a0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
192b0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
192c0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
192d0 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
192e0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
192f0 62 65 20 68 61 64 20 62 79 20 70 61 73 73 69 6e  be had by passin
19300 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
19310 65 74 65 72 20 74 68 61 74 20 0a 2a 2a 20 69 73  eter that .** is
19320 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
19330 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
19340 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
19350 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
19360 69 3e 20 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  i> .** the nul-t
19370 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
19380 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  {END}.**.** *pzT
19390 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
193a0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
193b0 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
193c0 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
193d0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
193e0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
193f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
19400 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
19410 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
19420 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
19430 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
19440 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
19450 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
19460 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
19470 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
19480 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
19490 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
194a0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
194b0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
194c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
194d0 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65 72  ()].  Or if ther
194e0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
194f0 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73 65 74  ppStmt is.** set
19500 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68   to NULL.  If th
19510 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
19520 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
19530 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73   the input.** is
19540 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e   and empty strin
19550 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
19560 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
19570 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
19580 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {U13018} The cal
19590 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
195a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
195b0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a  r deleting the.*
195c0 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73  * compiled SQL s
195d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e  tatement.** usin
195e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
195f0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
19600 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
19610 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
19620 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
19630 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
19640 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 0a    Otherwise an .
19650 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
19660 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
19670 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
19680 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
19690 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
196a0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
196b0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
196c0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
196d0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
196e0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
196f0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
19700 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
19710 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
19720 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
19730 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
19740 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
19750 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
19760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
19770 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
19780 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
19790 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
197a0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
197b0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67   of the .** orig
197c0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b  inal SQL text. {
197d0 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73  END} This causes
197e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
197f0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
19800 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
19810 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
19820 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
19830 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
19840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
19850 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
19860 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
19870 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
19880 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
19890 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
198a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
198b0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
198c0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
198d0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
198e0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
198f0 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
19900 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
19910 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
19920 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
19930 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
19940 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
19950 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19960 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
19970 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
19980 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
19990 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
199a0 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  or, .** [SQLITE_
199b0 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61  SCHEMA] is now a
199c0 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
199d0 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  alling.** [sqlit
199e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
199f0 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
19a00 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
19a10 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
19a20 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
19a30 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
19a40 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
19a50 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
19a60 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
19a70 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
19a80 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e  EMA] return. {EN
19a90 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  D}.** </li>.**.*
19aa0 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61  * <li>.** When a
19ab0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
19ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
19ad0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
19ae0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
19af0 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  iled .** [error 
19b00 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
19b10 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
19b20 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79  . .** The legacy
19b30 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
19b40 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  at [sqlite3_step
19b50 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
19b60 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a  eturn a generic.
19b70 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
19b80 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e  ] result code an
19b90 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
19ba0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
19bb0 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  d call to.** [sq
19bc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69  lite3_reset()] i
19bd0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
19be0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
19bf0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
19c00 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  lem..** With the
19c10 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 6e   "v2" prepare in
19c20 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
19c30 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
19c40 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
19c50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d  .** returned imm
19c60 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
19c70 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  i>.** </ol>.**.*
19c80 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
19c90 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 65  .** {F13011} The
19ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19cb0 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  e(db,zSql,...)] 
19cc0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
19cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19ce0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
19cf0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
19d00 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
19d10 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
19d20 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
19d30 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  ter as UTF-8..**
19d40 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 65  .** {F13012} The
19d50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19d60 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  e16(db,zSql,...)
19d70 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
19d80 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
19d90 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  re16_v2(db,zSql,
19da0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
19db0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
19dc0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
19dd0 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
19de0 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31  rameter as UTF-1
19df0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
19e00 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
19e10 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 68  * {F13013} If th
19e20 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
19e30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
19e40 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
19e50 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
19e60 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
19e70 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73  variants is less
19e80 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
19e90 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20   SQL text is.** 
19ea0 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72           read fr
19eb0 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  om zSql is read 
19ec0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
19ed0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
19ee0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20  .**.** {F13014} 
19ef0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
19f00 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
19f10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
19f20 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
19f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
19f40 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
19f50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
19f60 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74  hen at most nByt
19f70 65 73 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  es bytes.**     
19f80 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73       SQL text is
19f90 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
19fa0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35 7d 20  .**.** {F13015} 
19fb0 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  In [sqlite3_prep
19fc0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
19fd0 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20  ,P,pzTail)] and 
19fe0 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20  its variants.** 
19ff0 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20           if the 
1a000 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20  zSql input text 
1a010 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68  contains more th
1a020 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65  an one SQL state
1a030 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
1a040 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e   and pzTail is n
1a050 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70  ot NULL, then *p
1a060 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1a070 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a   point to the.**
1a080 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
1a090 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
1a0a0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1a0b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1a0c0 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20  zSql..**        
1a0d0 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65    <todo>What doe
1a0e0 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20  s *pzTail point 
1a0f0 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f  to if there is o
1a100 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74  ne statement?</t
1a110 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  odo>.**.** {F130
1a120 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  16} A successful
1a130 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1a140 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1a150 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e  zSql,N,ppStmt,..
1a160 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1a170 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1a180 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e  riants writes in
1a190 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69  to *ppStmt a poi
1a1a0 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
1a1b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1a1c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1a1d0 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  r a pointer to N
1a1e0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
1a1f0 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
1a200 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
1a210 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f  han whitespace o
1a220 72 20 63 6f 6d 6d 65 6e 74 73 2e 20 0a 2a 2a 0a  r comments. .**.
1a230 2a 2a 20 7b 46 31 33 30 31 39 7d 20 54 68 65 20  ** {F13019} The 
1a240 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a250 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1a260 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1a270 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
1a280 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
1a290 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
1a2a0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
1a2b0 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
1a2c0 0a 2a 2a 20 7b 46 31 33 30 32 31 7d 20 42 65 66  .** {F13021} Bef
1a2d0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
1a2e0 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
1a2f0 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
1a300 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
1a310 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
1a320 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
1a330 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
1a340 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
1a350 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ]).**          i
1a360 74 20 66 69 72 73 74 20 73 65 74 73 20 2a 70 70  t first sets *pp
1a370 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  Stmt to NULL..*/
1a380 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1a390 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
1a3a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1a3b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1a3c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1a3d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1a3e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1a3f0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1a400 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1a410 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1a420 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1a430 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1a440 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1a450 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1a460 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1a470 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a480 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1a490 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1a4a0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1a4b0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1a4c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1a4d0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1a4e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1a4f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1a500 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1a510 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1a520 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1a530 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1a540 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1a550 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1a560 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1a570 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1a580 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1a590 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1a5a0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1a5b0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1a5c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1a5d0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1a5e0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1a5f0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1a600 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1a610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1a620 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a630 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a640 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a650 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1a660 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a670 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a680 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1a690 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a6a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a6b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a6c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a6d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a6e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a6f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a700 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a710 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1a720 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a730 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a740 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a750 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1a760 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1a770 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1a780 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1a790 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1a7a0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1a7b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1a7c0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1a7d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1a7e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1a7f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1a800 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1a810 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1a820 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1a830 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1a840 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1a850 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1a860 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1a870 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1a880 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1a890 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1a8a0 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76  CAPIREF: Retriev
1a8b0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
1a8c0 4c 20 7b 46 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a  L {F13100}.**.**
1a8d0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1a8e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a8f0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
1a900 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
1a910 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
1a920 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
1a930 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1a940 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49  tement]..**.** I
1a950 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1a960 20 7b 46 31 33 31 30 31 7d 20 49 66 20 74 68 65   {F13101} If the
1a970 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a980 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1a990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a9a0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20   an argument to 
1a9b0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1a9c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
1a9d0 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69 6c 65           compile
1a9e0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1a9f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1aa00 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
1aa10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1aa20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
1aa30 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
1aa40 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1aa50 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1aa60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
1aa70 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1aa80 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1aa90 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20  ng containing a 
1aaa0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a  UTF-8 rendering.
1aab0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
1aac0 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  he original SQL 
1aad0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1aae0 20 7b 46 31 33 31 30 32 7d 20 49 66 20 74 68 65   {F13102} If the
1aaf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ab00 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
1ab10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ab20 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20   an argument to 
1ab30 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1ab40 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
1ab50 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69 6c 65           compile
1ab60 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1ab70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ab80 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1ab90 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1aba0 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  re16()],.**     
1abb0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
1abc0 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69  e3_sql()] functi
1abd0 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  on returns a NUL
1abe0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1abf0 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73 74   {F13103} The st
1ac00 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
1ac10 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29   [sqlite3_sql(S)
1ac20 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ] is valid until
1ac30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ac40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ac50 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74  ment] S is delet
1ac60 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1ac70 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a  3_finalize(S)]..
1ac80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1ac90 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
1aca0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1acb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1acc0 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  :  Dynamically T
1acd0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1ace0 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b  t  {F15000}.** K
1acf0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
1ad00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ad10 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
1ad20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
1ad30 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1ad40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
1ad50 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
1ad60 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
1ad70 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1ad80 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
1ad90 61 62 61 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20  abase table..** 
1ada0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1adb0 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74  mic typing for t
1adc0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
1add0 72 65 73 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73  res.  .** Values
1ade0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
1adf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ae00 20 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e   can be.** be in
1ae10 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1ae20 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1ae30 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1ae40 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1ae50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ae60 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1ae70 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1ae80 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1ae90 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1aea0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1aeb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1aec0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1aed0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1aee0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1aef0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1af00 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1af10 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1af20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1af30 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1af40 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1af50 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 20 0a  ents specifies .
1af60 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1af70 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1af80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1af90 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1afa0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1afb0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1afc0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1afd0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1afe0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1aff0 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1b000 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1b010 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1b020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1b030 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1b040 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1b050 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1b060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1b070 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1b080 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1b090 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1b0a0 65 64 0a 2a 2a 20 28 77 69 74 68 20 53 51 4c 49  ed.** (with SQLI
1b0b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 20  TE_THREADSAFE=0 
1b0c0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1b0d0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1b0e0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1b0f0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1b100 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1b110 77 65 65 6e 0a 2a 2a 20 70 72 6f 74 65 63 74 65  ween.** protecte
1b120 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1b130 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1b140 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1b150 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 20   can be.** used 
1b160 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 65 2e  interchangeable.
1b170 20 20 48 6f 77 65 76 65 72 2c 20 66 6f 72 20 6d    However, for m
1b180 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
1b190 61 62 69 6c 69 74 79 20 69 74 0a 2a 2a 20 69 73  ability it.** is
1b1a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1b1b0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  t applications m
1b1c0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
1b1d0 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 62  ion between.** b
1b1e0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1b1f0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1b200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1b210 62 6a 65 63 74 73 20 65 76 65 6e 20 69 66 0a 2a  bjects even if.*
1b220 2a 20 74 68 65 79 20 61 72 65 20 73 69 6e 67 6c  * they are singl
1b230 65 20 74 68 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a  e threaded..**.*
1b240 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
1b250 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
1b260 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
1b270 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
1b280 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
1b290 74 69 6f 6e 20 6f 66 20 61 70 70 6c 69 63 61 74  tion of applicat
1b2a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1b2b0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 70 72  functions are pr
1b2c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20  otected..** The 
1b2d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1b2e0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
1b2f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
1b300 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
1b310 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
1b320 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
1b330 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1b340 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
1b350 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
1b360 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
1b370 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1b380 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 20  _bind_value()]. 
1b390 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 69 6e   All other.** in
1b3a0 74 65 72 66 61 63 65 73 20 74 68 61 74 20 75 73  terfaces that us
1b3b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1b3c0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
1b3d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1b3e0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
1b3f0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
1b400 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
1b410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1b420 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
1b430 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36  text Object {F16
1b440 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  001}.**.** The c
1b450 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
1b460 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
1b470 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
1b480 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
1b490 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
1b4a0 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ct.  A pointer t
1b4b0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
1b4c0 74 65 78 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 69  text.** object i
1b4d0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
1b4e0 61 72 61 6d 65 74 65 72 20 74 6f 20 61 70 70 6c  arameter to appl
1b4f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1b500 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  SQL functions..*
1b510 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1b520 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1b530 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1b540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b550 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  F:  Binding Valu
1b560 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
1b570 74 61 74 65 6d 65 6e 74 73 20 7b 46 31 33 35 30  tatements {F1350
1b580 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  0}.**.** In the 
1b590 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75  SQL strings inpu
1b5a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1b5b0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1b5c0 69 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73 2c  its.** variants,
1b5d0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
1b5e0 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70 61   replace by a pa
1b5f0 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a  rameter in one.*
1b600 2a 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  * of these forms
1b610 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1b620 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
1b630 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
1b640 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
1b650 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
1b660 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
1b670 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
1b680 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
1b690 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
1b6a0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
1b6b0 56 56 56 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69  VVV alpha-numeri
1b6c0 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
1b6d0 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20  ..** The values 
1b6e0 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
1b6f0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1b700 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1b710 20 6e 61 6d 65 73 22 0a 2a 2a 20 6f 72 20 22 53   names".** or "S
1b720 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
1b730 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
1b740 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1b750 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1b760 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
1b770 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1b780 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1b790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1b7a0 20 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73   routines always
1b7b0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
1b7c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1b7d0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
1b7e0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
1b7f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1b800 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1b810 69 61 6e 74 73 2e 20 54 68 65 20 73 65 63 6f 6e  iants. The secon
1b820 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
1b830 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1b840 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  e parameter to b
1b850 65 20 73 65 74 2e 20 54 68 65 0a 2a 2a 20 66 69  e set. The.** fi
1b860 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  rst parameter ha
1b870 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
1b880 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20    When the same 
1b890 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65 74  named.** paramet
1b8a0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1b8b0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1b8c0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1b8d0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1b8e0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1b8f0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1b900 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a 2a   occurrence. .**
1b910 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e   The index for n
1b920 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1b930 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1b940 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1b950 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1b960 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50  meter_name()] AP
1b970 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
1b980 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
1b990 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
1b9a0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
1b9b0 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e  f NNN..** The NN
1b9c0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
1b9d0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
1b9e0 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  e compile-time.*
1b9f0 2a 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49  * parameter SQLI
1ba00 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
1ba10 4e 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20  NUMBER (default 
1ba20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
1ba30 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
1ba40 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
1ba50 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
1ba60 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
1ba70 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72  ** In those.** r
1ba80 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
1ba90 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
1baa0 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
1bab0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1bac0 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20  bytes.** in the 
1bad0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
1bae0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
1baf0 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
1bb00 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1bb10 0a 2a 2a 20 69 6e 20 74 68 65 20 76 61 6c 75 65  .** in the value
1bb20 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
1bb30 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20   of characters. 
1bb40 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
1bb50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
1bb60 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
1bb70 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
1bb80 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
1bb90 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
1bba0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1bbb0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1bbc0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67  ** The fifth arg
1bbd0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1bbe0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1bbf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1bc00 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1bc10 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1bc20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1bc30 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1bc40 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1bc50 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1bc60 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1bc70 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74  ed with it. If t
1bc80 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1bc90 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
1bca0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
1bcb0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
1bcc0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
1bcd0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
1bce0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
1bcf0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
1bd00 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
1bd10 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
1bd20 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
1bd30 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
1bd40 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
1bd50 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1bd60 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
1bd70 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
1bd80 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
1bd90 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
1bda0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
1bdb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1bdc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1bdd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1bde0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1bdf0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
1be00 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
1be10 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
1be20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
1be30 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75  s.  A zeroblob u
1be40 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
1be50 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
1be60 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
1be70 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65   to hold it size
1be80 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1be90 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1bea0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1beb0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1bec0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1bed0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1bee0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1bef0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1bf00 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
1bf10 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
1bf20 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d  rement BLOB I/O]
1bf30 20 72 6f 75 74 69 6e 65 73 2e 20 41 20 6e 65 67   routines. A neg
1bf40 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66  ative.** value f
1bf50 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
1bf60 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
1bf70 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
1bf80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1bf90 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1bfa0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
1bfb0 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
1bfc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1bfd0 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
1bfe0 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
1bff0 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
1c000 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
1c010 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
1c020 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
1c030 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
1c040 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
1c050 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
1c060 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
1c070 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
1c080 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
1c090 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1c0a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
1c0b0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
1c0c0 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
1c0d0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
1c0e0 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
1c0f0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
1c100 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
1c110 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
1c120 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
1c130 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
1c140 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
1c150 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  oc() fails..** [
1c160 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
1c170 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
1c180 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
1c190 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
1c1a0 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61   a.** virtual ma
1c1b0 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
1c1c0 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
1c1d0 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
1c1e0 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
1c1f0 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20  d..** Detection 
1c200 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72  of misuse is unr
1c210 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63  eliable.  Applic
1c220 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
1c230 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53  t depend.** on S
1c240 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74  QLITE_MISUSE ret
1c250 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49  urns.  SQLITE_MI
1c260 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64  SUSE is intended
1c270 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a   to indicate a.*
1c280 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  * a logic error 
1c290 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  in the applicati
1c2a0 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  on.  Future vers
1c2b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1c2c0 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61  ight.** panic ra
1c2d0 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
1c2e0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
1c2f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1c300 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1c310 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1c320 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1c330 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1c340 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
1c350 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1c360 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1c370 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1c380 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 7d 20  .**.** {F13506} 
1c390 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1c3a0 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65  pare | SQL state
1c3b0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72  ment compiler] r
1c3c0 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20 20 20  ecognizes.**    
1c3d0 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f 66 20        tokens of 
1c3e0 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c 20 22  the forms "?", "
1c3f0 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22  ?NNN", "$VVV", "
1c400 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56  :VVV", and "@VVV
1c410 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ".**          as
1c420 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c   SQL parameters,
1c430 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e   where NNN is an
1c440 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
1c450 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
1c460 20 20 20 20 20 20 64 69 67 69 74 73 20 61 6e 64        digits and
1c470 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e   where VVV is an
1c480 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
1c490 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20 20 20  e or more .**   
1c4a0 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75 6d 65         alphanume
1c4b0 72 69 63 20 63 68 61 72 61 63 74 65 72 73 20 6f  ric characters o
1c4c0 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c  r "::" optionall
1c4d0 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 2a 2a  y followed by.**
1c4e0 20 20 20 20 20 20 20 20 20 20 61 20 73 74 72 69            a stri
1c4f0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6e 6f  ng containing no
1c500 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74   spaces and cont
1c510 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72  ained within par
1c520 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  entheses..**.** 
1c530 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69  {F13509} The ini
1c540 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e  tial value of an
1c550 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1c560 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s NULL..**.** {F
1c570 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78  13512} The index
1c580 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70   of an "?" SQL p
1c590 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1c5a0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a  larger than the.
1c5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67  **          larg
1c5c0 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c  est index of SQL
1c5d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c5e0 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a  e left, or 1 if.
1c5f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1c600 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d  "?" is the leftm
1c610 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
1c620 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 35  r..**.** {F13515
1c630 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
1c640 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72  n "?NNN" SQL par
1c650 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e  ameter is the in
1c660 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a  teger NNN..**.**
1c670 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20 69 6e   {F13518} The in
1c680 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22  dex of an ":VVV"
1c690 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56  , "$VVV", or "@V
1c6a0 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  VV" SQL paramete
1c6b0 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
1c6c0 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65   the same as the
1c6d0 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f   index of leftmo
1c6e0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f  st occurrences o
1c6f0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  f the same.**   
1c700 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
1c710 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68  , or one more th
1c720 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  an the largest i
1c730 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a  ndex over all.**
1c740 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
1c750 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74  ters to the left
1c760 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
1c770 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1c780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1c790 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20  this parameter, 
1c7a0 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20  or 1 if this is 
1c7b0 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72  the leftmost par
1c7c0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ameter..**.** {F
1c7d0 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13521} The [sqli
1c7e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51  te3_prepare | SQ
1c7f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1c800 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68 0a  iler] fail with.
1c810 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 5b  **          an [
1c820 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65 72  SQLITE_RANGE] er
1c830 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65 78  ror if the index
1c840 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1c850 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
1c860 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 20   is less than 1 
1c870 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
1c880 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
1c890 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a 2a  BLE_NUMBER..**.*
1c8a0 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {F13524} Calls
1c8b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c8c0 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
1c8d0 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
1c8e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
1c8f0 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
1c900 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
1c910 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
1c920 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
1c930 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
1c940 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1c950 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
1c960 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {F13527} Calls
1c970 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c980 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
1c990 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
1c9a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
1c9b0 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
1c9c0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
1c9d0 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
1c9e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30 7d  ..**.** {F13530}
1c9f0 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
1ca00 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
1ca10 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
1ca20 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
1ca30 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
1ca40 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
1ca50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1ca60 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
1ca70 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {F13533} In cal
1ca80 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1ca90 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1caa0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1cab0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1cac0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1cad0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1cae0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1caf0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1cb00 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
1cb10 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
1cb20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
1cb30 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72 69  the blob or stri
1cb40 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
1cb50 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
1cb60 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
1cb70 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
1cb80 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
1cb90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1cba0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1cbb0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
1cbc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1cbd0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1cbe0 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
1cbf0 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
1cc00 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
1cc10 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
1cc20 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
1cc30 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
1cc40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39 7d  ..**.** {F13539}
1cc50 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1cc60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1cc70 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
1cc80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1cc90 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1cca0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
1ccb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ccc0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1ccd0 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
1cce0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
1ccf0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
1cd00 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
1cd10 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
1cd20 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
1cd30 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
1cd40 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
1cd50 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
1cd60 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
1cd70 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
1cd80 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
1cd90 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
1cda0 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  inding..**.** {F
1cdb0 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
1cdc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1cdd0 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
1cde0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
1cdf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1ce00 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
1ce10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1ce20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1ce30 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
1ce40 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
1ce50 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
1ce60 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
1ce70 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
1ce80 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
1ce90 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  a .**          p
1cea0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 56  rivate copy of V
1ceb0 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69 74   value before it
1cec0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1ced0 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c  {F13545} In call
1cee0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1cef0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
1cf00 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
1cf10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1cf20 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
1cf30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1cf40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1cf50 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
1cf60 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69   when D is a poi
1cf70 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  nter to.**      
1cf80 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20      a function, 
1cf90 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
1cfa0 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  hat function to 
1cfb0 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20  destroy the.**  
1cfc0 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65 20          V value 
1cfd0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1cfe0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
1cff0 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  V value..**.** {
1d000 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73  F13548} In calls
1d010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1d020 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56  d_zeroblob(S,N,V
1d030 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62  ,L)] the value b
1d040 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ound.**         
1d050 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c 20   is a blob of L 
1d060 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f  bytes, or a zero
1d070 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66 20  -length blob if 
1d080 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  L is negative..*
1d090 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49 6e  *.** {F13551} In
1d0a0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1d0b0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c  e3_bind_value(S,
1d0c0 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75  N,V)] the V argu
1d0d0 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20  ment may.**     
1d0e0 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61       be either a
1d0f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
1d100 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
1d110 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20  t or an.**      
1d120 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64      [unprotected
1d130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
1d140 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
1d150 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1d160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1d170 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1d180 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1d190 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1d1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
1d1b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1d1c0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
1d1d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1d1e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
1d1f0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
1d200 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1d210 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
1d220 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
1d230 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
1d240 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
1d250 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d260 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1d270 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
1d280 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1d290 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
1d2a0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1d2b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1d2c0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
1d2d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1d2e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1d2f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1d300 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1d310 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
1d320 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1d330 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
1d340 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1d350 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
1d360 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d370 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1d380 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1d390 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
1d3a0 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a  ers {F13600}.**.
1d3b0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1d3c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
1d3d0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
1d3e0 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  f SQL parameters
1d3f0 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72 65  .** in a prepare
1d400 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 51  d statement.  SQ
1d410 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
1d420 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
1d430 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
1d440 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
1d450 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
1d460 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
1d470 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1d480 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
1d490 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1d4a0 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
1d4b0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
1d4c0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
1d4d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
1d4e0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
1d4f0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
1d500 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  of the largest p
1d510 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46 6f 72  arameter..** For
1d520 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
1d530 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
1d540 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
1d550 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1d560 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
1d570 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
1d580 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61  rs of the ?NNN a
1d590 72 65 20 75 73 65 64 2c 20 74 68 65 72 65 20 6d  re used, there m
1d5a0 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20 69 6e  ay.** be gaps in
1d5b0 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a   the list..**.**
1d5c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1d5d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1d5e0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1d5f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1d600 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1d610 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1d620 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d630 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1d640 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1d650 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54 68 65  .** {F13601} The
1d660 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d670 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53  arameter_count(S
1d680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1d690 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
1d6a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
1d6b0 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61  ex of all SQL pa
1d6c0 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a  rameters in the.
1d6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1d6e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d6f0 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a 2a 2a   S, or 0 if S.**
1d700 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69            contai
1d710 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  ns no SQL parame
1d720 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ters..*/.int sql
1d730 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d740 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
1d750 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1d760 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
1d770 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
1d780 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a  ter {F13620}.**.
1d790 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1d7a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d7b0 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
1d7c0 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53 51 4c   the n-th.** SQL
1d7d0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20   parameter in a 
1d7e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d7f0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
1d800 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1d810 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
1d820 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
1d830 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
1d840 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
1d850 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
1d860 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
1d870 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1d880 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
1d890 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
1d8a0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
1d8b0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
1d8c0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
1d8d0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
1d8e0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
1d8f0 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
1d900 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
1d910 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
1d920 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
1d930 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  name..**.** The 
1d940 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
1d950 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1d960 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
1d970 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
1d980 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
1d990 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
1d9a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1d9b0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
1d9c0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
1d9d0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
1d9e0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
1d9f0 6c 77 61 79 73 20 69 6e 20 74 68 65 20 55 54 46  lways in the UTF
1da00 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
1da10 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
1da20 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
1da30 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
1da40 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
1da50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1da60 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
1da70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1da80 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
1da90 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1daa0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1dab0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1dac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1dad0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
1dae0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1daf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1db00 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
1db10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1db20 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b 73   {F13621} The [s
1db30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1db40 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d  meter_name(S,N)]
1db50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1db60 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
1db70 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1db80 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   of the name of 
1db90 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1dba0 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r in.**         
1dbb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dbc0 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69  ment] S having i
1dbd0 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20  ndex N, or.**   
1dbe0 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74         NULL if t
1dbf0 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70  here is no SQL p
1dc00 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e  arameter with in
1dc10 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a  dex N or if the.
1dc20 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
1dc30 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
1dc40 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f   N is an anonymo
1dc50 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22  us parameter "?"
1dc60 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
1dc70 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
1dc80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
1dc90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
1dca0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dcb0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
1dcc0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
1dcd0 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36 34  iven Name {F1364
1dce0 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0}.**.** Return 
1dcf0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
1dd00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
1dd10 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54  ven its name.  T
1dd20 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
1dd30 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
1dd40 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
1dd50 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
1dd60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1dd70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1dd80 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
1dd90 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72    A zero.** is r
1dda0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
1ddb0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
1ddc0 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20   is found.  The 
1ddd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
1dde0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
1ddf0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
1de00 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1de10 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
1de20 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
1de30 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
1de40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1de50 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1de60 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1de70 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1de80 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1de90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1dea0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1deb0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1dec0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ded0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1dee0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1def0 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65 20  ** {F13641} The 
1df00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1df10 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c  rameter_index(S,
1df20 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1df30 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1df40 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53    the index of S
1df50 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
1df60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1df70 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
1df80 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61   S whose name ma
1df90 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20  tches the UTF-8 
1dfa0 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69  string N, or 0 i
1dfb0 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20  f there is.**   
1dfc0 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e         no match.
1dfd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1dfe0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1dff0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
1e000 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
1e010 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
1e020 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
1e030 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
1e040 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1e050 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a  ent {F13660}.**.
1e060 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  ** Contrary to t
1e070 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
1e080 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
1e090 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
1e0a0 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b 73  .** reset the [s
1e0b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1e0c0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
1e0d0 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  a .** [prepared 
1e0e0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 65  statement].  Use
1e0f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
1e100 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 6f  .** reset all ho
1e110 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
1e120 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   NULL..**.** INV
1e130 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1e140 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c  F13661} The [sql
1e150 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
1e160 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ngs(S)] interfac
1e170 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a 20  e resets all.** 
1e180 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61 72           SQL par
1e190 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20  ameter bindings 
1e1a0 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  in [prepared sta
1e1b0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
1e1c0 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e 55        back to NU
1e1d0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
1e1e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
1e1f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
1e200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e210 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
1e220 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
1e230 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a   Set {F13710}.**
1e240 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
1e250 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1e260 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
1e270 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
1e280 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
1e290 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69   statement]. Thi
1e2a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1e2b0 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 20  s 0.** if pStmt 
1e2c0 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  is an SQL statem
1e2d0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
1e2e0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
1e2f0 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 61  or .** example a
1e300 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a 2a  n UPDATE)..**.**
1e310 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1e320 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65 20  ** {F13711} The 
1e330 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e340 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
1e350 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1e360 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
1e370 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e        columns in
1e380 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e390 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65  generated by the
1e3a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
1e3b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e3c0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 64  ] S, or 0 if S d
1e3d0 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65  oes not generate
1e3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
1e3f0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e  esult set..*/.in
1e400 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
1e410 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1e420 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1e430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1e440 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
1e450 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37  Result Set {F137
1e460 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  20}.**.** These 
1e470 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1e480 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
1e490 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
1e4a0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
1e4b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
1e4c0 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
1e4d0 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
1e4e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
1e4f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
1e500 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1e510 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
1e520 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ted UTF8 string.
1e530 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1e540 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
1e550 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1e560 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
1e570 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20 73  nated.** UTF16 s
1e580 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73  tring.  The firs
1e590 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1e5a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1e5b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1e5c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53  implements the S
1e5d0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1e5e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
1e5f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1e600 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
1e610 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
1e620 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65  lumn is.** numbe
1e630 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
1e640 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
1e650 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
1e660 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
1e670 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
1e680 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
1e690 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
1e6a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
1e6b0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
1e6c0 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ext call sqlite3
1e6d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
1e6e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
1e6f0 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e 20  _name16().** on 
1e700 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
1e710 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
1e720 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
1e730 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
1e740 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
1e750 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
1e760 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
1e770 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
1e780 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
1e790 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
1e7a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
1e7b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1e7c0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
1e7d0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
1e7e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
1e7f0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
1e800 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
1e810 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
1e820 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
1e830 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
1e840 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
1e850 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
1e860 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
1e870 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
1e880 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
1e890 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
1e8a0 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49  he next..**.** I
1e8b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1e8c0 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63 63   {F13721} A succ
1e8d0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1e8e0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
1e8f0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
1e900 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
1e910 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1e920 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
1e930 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74         of the Nt
1e940 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20  h column (where 
1e950 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f  0 is the left-mo
1e960 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
1e970 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
1e980 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
1e990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e9a0 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20  ] S as a.**     
1e9b0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
1e9c0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1e9d0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 33  g..**.** {F13723
1e9e0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
1e9f0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
1ea00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ea10 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  _name16(S,N)].**
1ea20 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1ea30 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1ea40 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
1ea50 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
1ea60 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 74  mn (where 0 is t
1ea70 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
1ea80 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20  umn) for the.** 
1ea90 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
1eaa0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
1eab0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
1eac0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
1ead0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1eae0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1eaf0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1eb00 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  order..**.** {F1
1eb10 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3724} The [sqlit
1eb20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1eb30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
1eb40 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a  olumn_name16()].
1eb50 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1eb60 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20  rfaces return a 
1eb70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1eb80 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20  they are unable 
1eb90 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
1eba0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1ebb0 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72  o hold their nor
1ebc0 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e  mal return strin
1ebd0 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  gs..**.** {F1372
1ebe0 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61  5} If the N para
1ebf0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1ec00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
1ec10 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
1ec20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
1ec30 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
1ec40 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1ec50 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
1ec60 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1ec70 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
1ec80 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b  ointer..** .** {
1ec90 46 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69  F13726} The stri
1eca0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1ecb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ecc0 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a  name(S,N)] and.*
1ecd0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1ece0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1ecf0 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69  6(S,N)] are vali
1ed00 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  d until the next
1ed10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
1ed20 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74  l to either rout
1ed30 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d  ine with the sam
1ed40 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65  e S and N parame
1ed50 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
1ed60 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
1ed70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
1ed80 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  is called..**.**
1ed90 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61   {F13727} When a
1eda0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1edb0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
1edc0 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a  tement contains.
1edd0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41  **          an A
1ede0 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61  S clause, the na
1edf0 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d  me of that colum
1ee00 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66  n is the identif
1ee10 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ier.**          
1ee20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20  to the right of 
1ee30 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a  the AS keyword..
1ee40 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1ee50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1ee60 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1ee70 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
1ee80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1ee90 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
1eea0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
1eeb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1eec0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
1eed0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
1eee0 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a  sult {F13740}.**
1eef0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1ef00 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
1ef10 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
1ef20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
1ef30 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
1ef40 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
1ef50 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c   result of a SEL
1ef60 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
1ef70 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65  mes from..** The
1ef80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1ef90 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
1efa0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
1efb0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
1efc0 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20  ither a UTF8 or 
1efd0 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
1efe0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1eff0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1f000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1f010 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1f020 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f030 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1f040 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1f050 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1f060 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1f070 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
1f080 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
1f090 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65  lid until.** the
1f0a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f0b0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
1f0c0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1f0d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1f0e0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
1f0f0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
1f100 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
1f110 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
1f120 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
1f130 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65  .** The names re
1f140 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
1f150 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
1f160 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
1f170 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
1f180 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
1f190 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1f1a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1f1b0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20  following calls 
1f1c0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
1f1d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
1f1e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
1f1f0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
1f200 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
1f210 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1f220 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  y .** the statem
1f230 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
1f240 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
1f250 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
1f260 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
1f270 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1f280 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
1f290 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
1f2a0 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20  .** or subquery 
1f2b0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
1f2c0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
1f2d0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
1f2e0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
1f2f0 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
1f300 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
1f310 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
1f320 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
1f330 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
1f340 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
1f350 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
1f360 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65   .** name of the
1f370 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1f380 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  se, table and co
1f390 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
1f3a0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
1f3b0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
1f3c0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
1f3d0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
1f3e0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
1f3f0 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
1f400 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
1f410 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
1f420 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
1f430 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1f440 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
1f450 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
1f460 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
1f470 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
1f480 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
1f490 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
1f4a0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
1f4b0 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
1f4c0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
1f4d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33  ined..**.** {U13
1f4e0 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
1f4f0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1f500 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
1f510 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1f520 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
1f530 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
1f540 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
1f550 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
1f560 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
1f570 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
1f580 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
1f590 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1f5a0 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {F13741} The [sq
1f5b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1f5c0 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
1f5d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f5e0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1f5f0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
1f600 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f610 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1f620 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
1f630 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1f640 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1f650 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1f660 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1f670 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1f680 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1f690 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
1f6a0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1f6b0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1f6c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1f6d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1f6e0 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1f6f0 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1f700 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1f710 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1f720 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1f730 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1f740 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
1f750 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1f760 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1f770 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
1f780 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
1f790 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1f7a0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1f7b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1f7c0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f7d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f7e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f7f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f800 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f810 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f820 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f830 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
1f840 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
1f850 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
1f860 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
1f870 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1f880 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
1f890 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
1f8a0 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
1f8b0 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20 54 68   .** {F13743} Th
1f8c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1f8d0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
1f8e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1f8f0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
1f900 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
1f910 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1f920 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
1f930 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
1f940 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1f950 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1f960 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1f970 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1f980 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1f990 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1f9a0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1f9b0 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f9c0 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f9d0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f9e0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f9f0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1fa00 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1fa10 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1fa20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34       .** {F13744
1fa30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1fa40 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
1fa50 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
1fa60 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1fa70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1fa80 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
1fa90 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
1faa0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1fab0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1fac0 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
1fad0 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1fae0 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1faf0 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1fb00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1fb10 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1fb20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1fb30 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
1fb40 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1fb50 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1fb60 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1fb70 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1fb80 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1fb90 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1fba0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1fbb0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1fbc0 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  13745} The [sqli
1fbd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1fbe0 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  n_name(S,N)] int
1fbf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1fc00 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1fc10 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
1fc20 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
1fc30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1fc40 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
1fc50 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1fc60 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1fc70 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1fc80 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1fc90 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1fca0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1fcb0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
1fcc0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1fcd0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1fce0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1fcf0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1fd00 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1fd10 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1fd20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1fd30 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1fd40 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
1fd50 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1fd60 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
1fd70 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1fd80 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1fd90 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
1fda0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
1fdb0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1fdc0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1fdd0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1fde0 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
1fdf0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
1fe00 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
1fe10 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
1fe20 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
1fe30 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
1fe40 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
1fe50 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1fe60 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
1fe70 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
1fe80 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
1fe90 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1fea0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
1feb0 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
1fec0 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
1fed0 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38 7d 20     .** {F13748} 
1fee0 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
1fef0 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
1ff00 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
1ff10 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1ff20 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61  |column metadata
1ff30 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
1ff40 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1ff50 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  id.**          f
1ff60 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  or the lifetime 
1ff70 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
1ff80 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
1ff90 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
1ffa0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
1ffb0 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74   changed by anot
1ffc0 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  her metadata.** 
1ffd0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1ffe0 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20  ce call for the 
1fff0 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74  same prepared st
20000 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
20010 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  mn..**.** LIMITA
20020 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
20030 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20  3751} If two or 
20040 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
20050 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
20060 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20070 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
20080 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d  se_name|column m
20090 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
200a0 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
200b0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
200c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
200d0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
200e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
200f0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
20100 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
20110 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
20120 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20140 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
20150 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
20160 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
20170 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
20180 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
20190 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
201a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
201b0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
201c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
201d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
201e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
201f0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
20200 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20210 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
20220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
20230 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
20240 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
20250 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
20260 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
20270 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
20280 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
20290 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
202a0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
202b0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
202c0 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13760}.**.** Th
202d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
202e0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
202f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a   statement]. .**
20300 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
20310 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73  nt is a SELECT s
20320 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
20330 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
20340 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  he .** returned 
20350 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
20360 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
20370 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
20380 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
20390 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
203a0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
203b0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
203c0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
203d0 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
203e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
203f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
20400 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
20410 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
20420 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
20430 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
20440 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
20450 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
20460 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
20470 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20    {END} .** For 
20480 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20  example, in the 
20490 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
204a0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
204b0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
204c0 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68  T);.**.** And th
204d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
204e0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a  ement compiled:.
204f0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
20500 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
20510 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73  .**.** Then this
20520 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
20530 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
20540 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
20550 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73  he second.** res
20560 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  ult column (i==1
20570 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
20580 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
20590 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
205a0 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  n.** (i==0)..**.
205b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
205c0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
205d0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
205e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
205f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
20600 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
20610 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
20620 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
20630 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
20640 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
20650 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
20660 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
20670 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
20680 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
20690 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
206a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
206b0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
206c0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
206d0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
206e0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
206f0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
20700 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
20710 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ues..**.** INVAR
20720 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
20730 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73  3761}  A success
20740 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
20750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
20760 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  type(S,N)].**   
20770 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
20780 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
20790 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
207a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
207b0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64             the d
207c0 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65  eclared datatype
207d0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
207e0 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
207f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  s.**           a
20800 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  s the Nth column
20810 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20   (numbered from 
20820 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
20830 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20   set to the.**  
20840 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
20850 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
20860 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32 7d 20  .**.** {F13762} 
20870 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
20880 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
20890 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
208a0 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
208b0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65      returns a ze
208c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
208d0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
208e0 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a   order string.**
208f0 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61             conta
20900 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72  ining the declar
20910 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ed datatype of t
20920 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
20930 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20  that appears.** 
20940 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
20950 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
20960 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
20970 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20980 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
20990 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
209a0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
209b0 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66 20 4e  * {F13763}  If N
209c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20   is less than 0 
209d0 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20  or N is greater 
209e0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
209f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
20a00 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
20a10 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64  mns in [prepared
20a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
20a30 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66             or if
20a40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
20a50 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65  of S is an expre
20a60 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
20a70 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20  y rather.**     
20a80 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62        than a tab
20a90 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69 66 20  le column or if 
20aa0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
20ab0 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
20ac0 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
20ad0 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
20ae0 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
20af0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
20b00 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20b10 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
20b20 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
20b30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20b40 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
20b50 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
20b60 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
20b70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
20b80 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
20b90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20ba0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
20bc0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
20bd0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a  mt*,int);../* .*
20be0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61  * CAPI3REF:  Eva
20bf0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
20c00 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a  tement {F13200}.
20c10 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b  **.** After an [
20c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20c30 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
20c40 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c  pared with a cal
20c50 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b  l.** to either [
20c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20c70 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
20c80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20c90 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a  ] or to one of.*
20ca0 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  * the legacy int
20cb0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
20cc0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
20cd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20ce0 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  6()],.** then th
20cf0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  is function must
20d00 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
20d10 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
20d20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a  evaluate the .**
20d30 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
20d40 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
20d50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
20d60 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74   this sqlite3_st
20d70 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
20d80 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
20d90 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
20da0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
20db0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
20dc0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
20dd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20de0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
20df0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20e00 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
20e10 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
20e20 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
20e30 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
20e40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20e50 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
20e60 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
20e70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
20e80 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
20e90 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
20ea0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
20eb0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
20ec0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
20ed0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
20ee0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
20ef0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
20f00 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
20f10 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
20f20 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  _BUSY], .** [SQL
20f30 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
20f40 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
20f50 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
20f60 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
20f70 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
20f80 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
20f90 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54  the other [SQLIT
20fa0 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
20fb0 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  de].** or [SQLIT
20fc0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
20fd0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
20fe0 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65  ode] might be re
20ff0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c  turned as.** wel
21000 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
21010 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
21020 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
21030 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
21040 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
21050 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
21060 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
21070 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
21080 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
21090 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63   COMMIT.** or oc
210a0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
210b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
210c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
210d0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
210e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
210f0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
21100 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20  is not a COMMIT 
21110 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
21120 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
21130 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
21140 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
21150 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
21160 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
21170 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
21180 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
21190 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
211a0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
211b0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
211c0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
211d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
211e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
211f0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
21200 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
21210 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
21220 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
21230 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
21240 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
21250 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
21260 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
21270 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
21280 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
21290 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
212a0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
212b0 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53  ata, then .** [S
212c0 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65  QLITE_ROW] is re
212d0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
212e0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
212f0 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66  ta is ready.** f
21300 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
21310 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65   the caller. The
21320 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
21330 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a  ccessed using.**
21340 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
21350 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d  lumn_int | colum
21360 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
21370 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
21380 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
21390 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
213a0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
213b0 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20  of data..** .** 
213c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
213d0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
213e0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
213f0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
21400 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
21410 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
21420 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
21430 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
21440 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
21450 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
21460 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
21470 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
21480 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
21490 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c  ]..** With the l
214a0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
214b0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
214c0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
214d0 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple:.** [SQLITE
214e0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
214f0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
21500 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
21510 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
21520 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
21530 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
21540 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
21550 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
21560 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
21570 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21580 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
21590 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
215a0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
215b0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
215c0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
215d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
215e0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
215f0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
21600 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
21610 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
21620 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
21630 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
21640 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
21650 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
21660 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
21670 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
21680 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
21690 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72   that had .** pr
216a0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
216b0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
216c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
216d0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
216e0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
216f0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
21700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21710 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
21720 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
21730 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
21740 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
21750 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
21760 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
21770 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74  ert:</b>.** In t
21780 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
21790 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c  ace, .** the sql
217a0 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 49 20  ite3_step() API 
217b0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
217c0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
217d0 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ode,.** [SQLITE_
217e0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
217f0 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65  g any error othe
21800 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
21810 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  USY].** and [SQL
21820 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
21830 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c  u must call [sql
21840 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
21850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
21860 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
21870 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
21880 20 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a   the specific.**
21890 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
218a0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
218b0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
218c0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
218d0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
218e0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
218f0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
21900 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
21910 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
21920 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
21930 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
21940 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
21950 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
21960 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21970 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21980 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
21990 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
219a0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
219b0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
219c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
219d0 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
219e0 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69  .** more specifi
219f0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
21a00 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
21a10 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
21a20 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
21a30 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
21a40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
21a50 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
21a60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
21a70 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66 20  ** {F13202}  If 
21a80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21a90 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
21aa0 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  to be.**        
21ab0 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b 73 71     run, then [sq
21ac0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
21ad0 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
21ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
21af0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75 6e 74  **           unt
21b00 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  il to completion
21b10 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20   or until it is 
21b20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20  ready to return 
21b30 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20 20 20  another.**      
21b40 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68 65 20       row of the 
21b50 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20 61 6e  result set or an
21b60 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20 72 75   interrupt or ru
21b70 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63  n-time error occ
21b80 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  urs..**.** {F153
21b90 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  04}  When a call
21ba0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
21bb0 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65  p(S)] causes the
21bc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b   .**           [
21bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21be0 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74 6f 20  nt] S to run to 
21bf0 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a 20 20  completion,.**  
21c00 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e           the fun
21c10 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
21c20 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a  QLITE_DONE]..**.
21c30 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 68 65  ** {F15306}  Whe
21c40 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
21c50 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74  ite3_step(S)] st
21c60 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69  ops because it i
21c70 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20 20 20  s ready.**      
21c80 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e 20 61       to return a
21c90 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
21ca0 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74  e result set, it
21cb0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
21cc0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
21cd0 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30  W]..**.** {F1530
21ce0 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  8}  If a call to
21cf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
21d00 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  )] encounters an
21d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
21d20 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
21d30 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61  |interrupt] or a
21d40 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
21d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
21d60 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
21d70 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
21d80 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
21d90 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
21da0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
21db0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
21dc0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
21dd0 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d 20 20  **.** {F15310}  
21de0 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
21df0 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75  nterrupt|interru
21e00 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20  pt] or run-time 
21e10 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  error.**        
21e20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
21e30 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21e40 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20  te3_step(S)].** 
21e50 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
21e60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21e70 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75  ent] S created u
21e80 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
21e90 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61    legacy interfa
21ea0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
21eb0 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
21ec0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
21ed0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 74 68  _prepare16()] th
21ee0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
21ef0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
21f00 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
21f10 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c  ITE_ERROR], [SQL
21f20 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53  ITE_BUSY], or [S
21f30 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
21f40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
21f50 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
21f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21f70 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
21f80 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
21f90 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d 0a 2a  t set {F13770}.*
21fa0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
21fb0 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
21fc0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
21fd0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
21fe0 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t set..**.** INV
21ff0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
22000 46 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61  F13771}  After a
22010 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
22020 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20  3_step(S)] that 
22030 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
22040 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
22050 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ], the [sqlite3_
22060 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
22070 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20  outine.**       
22080 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
22090 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
220a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
220b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
220c0 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e  mn_count(S)] fun
220d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
220e0 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71  3772}  After [sq
220f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
22100 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20  as returned any 
22110 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
22120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
22130 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65  QLITE_ROW] or be
22140 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
22150 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20  ep(S)] has been 
22160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
22170 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70 72 65  lled on the [pre
22180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22190 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
221a0 20 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65    the first time
221b0 20 73 69 6e 63 65 20 69 74 20 77 61 73 20 5b 73   since it was [s
221c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 7c 70  qlite3_prepare|p
221d0 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20 20 20  repared].**     
221e0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
221f0 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d 2c 20  3_reset|reset], 
22200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
22210 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a 20 20  a_count(S)].**  
22220 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
22230 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
22240 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
22250 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
22260 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
22270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22280 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
22290 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d 0a 2a  types {F10265}.*
222a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
222b0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46  TE_TEXT.**.** {F
222c0 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 6c 75  10266}Every valu
222d0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
222e0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
222f0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
22300 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22310 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
22320 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
22330 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
22340 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
22350 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
22360 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
22370 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
22380 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
22390 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
223a0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
223b0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
223c0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
223d0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
223e0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
223f0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
22400 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22410 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
22420 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
22430 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
22440 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
22450 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
22460 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
22470 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
22480 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
22490 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a  QLITE3_TEXT not.
224a0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
224b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
224c0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
224d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
224e0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
224f0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
22500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22510 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
22520 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
22530 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
22540 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
22550 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
22560 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
22570 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
22580 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
22590 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61  3REF: Results Va
225a0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
225b0 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a  y {F13800}.**.**
225c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
225d0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
225e0 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65   set query" inte
225f0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
22600 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
22610 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
22620 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  bout.** a single
22630 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
22640 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72 6f  urrent result ro
22650 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49  w of a query.  I
22660 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 20  n every.** case 
22670 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
22680 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
22690 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  to the .** [prep
226a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
226b0 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a  that is being.**
226c0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
226d0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
226e0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
226f0 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
22700 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22710 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
22720 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a  variants) and.**
22730 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
22740 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
22750 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
22760 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
22770 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64  ation .** should
22780 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
22790 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
227a0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
227b0 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20  t set.** has an 
227c0 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a  index of 0..**.*
227d0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
227e0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75  tement is not cu
227f0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
22800 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
22810 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63   if the.** the c
22820 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
22830 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
22840 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
22850 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20  ined. .** These 
22860 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
22870 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
22880 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22890 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
228a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
228b0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
228c0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
228d0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
228e0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
228f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22900 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73   has been call s
22910 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
22920 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
22930 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
22940 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
22950 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
22960 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
22970 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
22980 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22990 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
229a0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
229b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
229c0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
229d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
229e0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
229f0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
22a00 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
22a10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22a20 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
22a30 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
22a40 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
22a50 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
22a60 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
22a70 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
22a80 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
22a90 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ned.  .**.** The
22aa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22ab0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
22ac0 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
22ad0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
22ae0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
22af0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
22b00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
22b10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
22b20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
22b30 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
22b40 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
22b50 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
22b60 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
22b70 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
22b80 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
22b90 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
22ba0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
22bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
22bc0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
22bd0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
22be0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
22bf0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
22c00 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
22c10 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
22c20 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
22c30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
22c40 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
22c50 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
22c60 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
22c70 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
22c80 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
22c90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
22ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22cb0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
22cc0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
22cd0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
22ce0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
22cf0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
22d00 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
22d10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22d20 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65  es() .** routine
22d30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
22d40 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
22d50 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
22d60 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
22d70 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
22d80 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
22d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22da0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
22db0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
22dc0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
22dd0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
22de0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
22df0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
22e00 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
22e10 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
22e20 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
22e30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
22e40 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
22e50 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
22e60 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
22e70 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
22e80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
22e90 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
22ea0 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
22eb0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
22ec0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
22ed0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
22ee0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
22ef0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
22f00 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
22f10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
22f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
22f30 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
22f40 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
22f50 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
22f60 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
22f70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
22f80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
22f90 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
22fa0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
22fb0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
22fc0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
22fd0 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
22fe0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a  ed.  The return.
22ff0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
23000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23010 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
23020 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61 6e  ength blob is an
23030 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
23040 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
23050 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
23060 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
23070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23080 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
23090 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
230a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
230b0 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
230c0 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
230d0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
230e0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
230f0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20  tead of UTF-8.  
23100 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
23110 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
23120 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
23130 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
23140 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23150 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
23160 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
23170 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
23180 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23190 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
231a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
231b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
231c0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
231d0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
231e0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
231f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
23200 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
23210 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
23220 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23230 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
23240 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
23250 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
23260 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
23270 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
23280 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
23290 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
232a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
232b0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
232c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
232d0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ], or [sqlite3_v
232e0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 0a 2a  alue_bytes()],.*
232f0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
23300 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
23310 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
23320 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
23330 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
23340 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
23350 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
23360 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
23370 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
23380 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
23390 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
233a0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
233b0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
233c0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
233d0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f  internally to do
233e0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a   the conversion.
233f0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
23400 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
23410 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
23420 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74  he conversions t
23430 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69  hat.** are appli
23440 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
23450 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
23460 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
23470 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
23480 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
23490 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
234a0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
234b0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
234c0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
234d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
234e0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
234f0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
23500 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
23510 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
23520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
23530 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
23540 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
23550 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
23560 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
23570 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
23580 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
23590 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
235a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
235b0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
235c0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
235d0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
235e0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
235f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
23600 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23610 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
23620 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
23630 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
23640 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
23650 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
23660 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45   for INTEGER->TE
23670 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
23680 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
23690 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
236a0 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
236b0 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
236c0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
236d0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
236e0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
236f0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
23700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
23710 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
23720 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
23730 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
23740 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23750 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
23760 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
23770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
23780 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
23790 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
237a0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
237b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
237c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
237d0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
237e0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
237f0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23800 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
23810 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
23820 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
23830 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
23840 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
23850 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
23860 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
23870 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
23880 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23890 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
238a0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
238b0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
238c0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
238d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
238e0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
238f0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
23900 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
23910 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
23920 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
23930 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
23940 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
23950 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
23960 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
23970 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
23980 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
23990 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
239a0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
239b0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
239c0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
239d0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
239e0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
239f0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
23a00 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
23a10 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
23a20 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
23a30 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
23a40 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
23a50 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23a60 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
23a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23a80 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
23a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23aa0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
23ab0 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20  nvalidated. .** 
23ac0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
23ad0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
23ae0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
23af0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
23b00 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
23b10 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
23b20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
23b30 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
23b40 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
23b50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23b60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72   .**          or
23b70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23b80 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23b90 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
23ba0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
23bb0 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f           need to
23bc0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
23bd0 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69   string.</p></li
23be0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
23bf0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
23c00 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
23c10 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
23c20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
23c30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
23c40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23c50 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
23c60 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
23c70 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
23c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
23c90 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e  UTF-16.</p></li>
23ca0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  .**.** <li><p>  
23cb0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
23cc0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
23cd0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
23ce0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
23cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
23d00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23d10 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
23d20 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
23d30 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
23d40 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
23d50 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  8.</p></li>.** <
23d60 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
23d70 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
23d80 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
23d90 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
23da0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
23db0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
23dc0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
23dd0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
23de0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
23df0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
23e00 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
23e10 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
23e20 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
23e30 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
23e40 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
23e50 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
23e60 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
23e70 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
23e80 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
23e90 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  e it is.** not p
23ea0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
23eb0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
23ec0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
23ed0 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a  validated.  .**.
23ee0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
23ef0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
23f00 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
23f10 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
23f20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
23f30 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
23f40 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
23f50 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
23f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23f70 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
23f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23f90 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
23fa0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
23fb0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
23fc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
23fd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
23fe0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
23ff0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24000 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
24010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24020 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  es16()</li>.**  
24030 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
24040 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
24050 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
24060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
24070 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
24080 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20  n_blob(),.** or 
24090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
240a0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
240b0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
240c0 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  t into the desir
240d0 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68  ed.** format, th
240e0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
240f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
24100 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24110 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a  mn_bytes16() to.
24120 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  ** find the size
24130 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
24140 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
24150 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
24160 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
24170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24180 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
24190 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
241a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41  mn_bytes16().  A
241b0 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78  nd do not.** mix
241c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
241d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
241e0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
241f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24200 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
24210 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
24220 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
24230 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
24240 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
24250 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
24260 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
24270 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
24280 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24290 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
242a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
242b0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
242c0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
242d0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
242e0 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20  ** and blobs is 
242f0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
24300 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
24310 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
24320 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
24330 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
24340 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
24350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
24360 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a  )], etc. into .*
24370 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
24380 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
24390 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
243a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
243b0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
243c0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
243d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
243e0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
243f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
24400 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
24410 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
24420 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
24430 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24440 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
24450 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
24460 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
24470 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24480 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
24490 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
244a0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
244b0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
244c0 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20 5b  * {F13803} The [
244d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
244e0 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(S,N)] interf
244f0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
24500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24510 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
24520 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
24530 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
24540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24560 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20  ] S into a blob 
24570 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
24580 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
24590 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
245a0 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a  nverted value..*
245b0 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54 68  *.** {F13806} Th
245c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
245d0 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e  n_bytes(S,N)] in
245e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
245f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24600 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
24610 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73  in the blob or s
24620 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
24630 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
24640 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
24650 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
24660 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
24670 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
24680 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
24690 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
246a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
246b0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
246c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
246d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
246e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39 7d  ..**.** {F13809}
246f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24700 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e  lumn_bytes16(S,N
24710 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24720 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
24730 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
24740 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
24750 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
24760 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24770 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
24780 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
24790 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
247a0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
247b0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
247c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
247d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
247e0 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  S,N)]..**.** {F1
247f0 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3812} The [sqlit
24800 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
24810 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
24820 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
24830 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
24840 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
24850 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
24860 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
24870 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
24880 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24890 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
248a0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
248b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
248c0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
248d0 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
248e0 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b 73   {F13815} The [s
248f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
24900 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  t(S,N)] interfac
24910 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
24920 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
24930 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
24940 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
24950 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
24960 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
24970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24980 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
24990 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
249a0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
249b0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
249c0 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
249d0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
249e0 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71  {F13818} The [sq
249f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
24a00 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  64(S,N)] interfa
24a10 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
24a20 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24a30 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24a40 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24a50 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24a60 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24a80 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
24a90 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
24aa0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
24ab0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
24ac0 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
24ad0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20 54  **.** {F13821} T
24ae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24af0 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e  mn_text(S,N)] in
24b00 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
24b10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24b20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
24b30 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
24b40 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
24b50 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
24b60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24b70 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a  ment] S into a z
24b80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
24b90 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20  TF-8 .**        
24ba0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
24bb0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
24bc0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
24bd0 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54 68  *.** {F13824} Th
24be0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24bf0 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69  n_text16(S,N)] i
24c00 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
24c10 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
24c20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
24c30 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24c40 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24c50 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24c60 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24c70 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
24c80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24c90 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
24ca0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
24cb0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
24cc0 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
24cd0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
24ce0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
24cf0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
24d00 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65 20  ** {F13827} The 
24d10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24d20 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  type(S,N)] inter
24d30 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
24d40 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
24d50 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
24d60 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
24d70 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
24d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
24d90 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
24da0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
24db0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
24dc0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
24dd0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
24de0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
24df0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
24e00 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
24e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24e20 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
24e30 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  13830} The [sqli
24e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
24e50 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
24e60 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
24e70 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
24e80 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  o an [unprotecte
24e90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
24ea0 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a   object for the.
24eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24ec0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24ed0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24ee0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24f00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24f10 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69   S..*/.const voi
24f20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24f30 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
24f40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24f50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24f60 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
24f70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24f80 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24f90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
24fa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24fb0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
24fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24fd0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
24fe0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
25000 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
25010 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25020 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
25030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
25040 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
25050 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
25060 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
25070 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25080 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
25090 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
250a0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
250b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
250c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
250d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
250e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
250f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
25100 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
25110 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
25120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
25130 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
25140 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
25150 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
25160 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
25170 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
25180 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13300}.**.**
25190 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
251a0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
251b0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
251c0 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65 70  lete a .** [prep
251d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
251e0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
251f0 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
25200 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
25210 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
25220 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
25230 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
25240 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
25250 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
25260 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
25270 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   an .** [error c
25280 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
25290 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  d error code].**
252a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a   is returned. .*
252b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
252c0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
252d0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
252e0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
252f0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
25300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25310 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
25320 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
25330 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  t .** completed 
25340 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
25350 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
25360 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
25370 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
25380 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
25390 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28  an interrupt.  (
253a0 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  See [sqlite3_int
253b0 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20  errupt()].) .** 
253c0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
253d0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
253e0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
253f0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64  ctions cancelled
25400 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ,  .** depending
25410 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
25420 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a  ances, and the .
25430 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
25440 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
25450 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
25460 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
25470 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 32  S:.**.** {F11302
25480 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
25490 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65  inalize(S)] inte
254a0 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74  rface destroys t
254b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
254c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
254d0 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73  nt] S and releas
254e0 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  es all.**       
254f0 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69     memory and fi
25500 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c  le resources hel
25510 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74  d by that object
25520 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34 7d  ..**.** {F11304}
25530 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
25540 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
25550 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
25560 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
25570 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
25580 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
25590 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  d an error,.**  
255a0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
255b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
255c0 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  )] returns that 
255d0 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69  same error..*/.i
255e0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
255f0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
25600 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
25610 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
25620 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
25630 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
25640 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3330}.**.** The 
25650 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
25660 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
25670 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a  ed to reset a .*
25680 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
25690 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a  ement] object..*
256a0 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  * back to its in
256b0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
256c0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
256d0 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
256e0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
256f0 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
25700 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
25710 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
25720 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25730 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
25740 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
25750 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
25760 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
25770 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
25780 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
25790 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
257a0 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  F11332} The [sql
257b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
257c0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
257d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
257e0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
257f0 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
25800 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
25810 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
25820 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20 74  ** {F11334} If t
25830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
25840 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25850 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a 2a  step(S)] for .**
25860 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
25870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25880 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
25890 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
258a0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
258b0 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
258c0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
258d0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
258e0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
258f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
25900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25910 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
25920 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
25930 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  F11336} If the m
25940 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
25950 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
25960 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  (S)] for.**     
25970 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
25980 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
25990 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
259a0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
259b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
259c0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
259d0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
259e0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  r code]..**.** {
259f0 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c  F11338} The [sql
25a00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
25a10 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
25a20 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
25a30 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
25a40 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
25a50 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
25a60 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65 64  gs] on [prepared
25a70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
25a80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
25a90 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
25aa0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
25ab0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
25ac0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
25ad0 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36  L Functions {F16
25ae0 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  100}.** KEYWORDS
25af0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
25b00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 20 0a  tion routines} .
25b10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
25b20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
25b30 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
25b40 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63 72  .** "function cr
25b50 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
25b60 29 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  ) are used to ad
25b70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
25b80 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
25b90 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
25ba0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
25bb0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
25bc0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
25bd0 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
25be0 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
25bf0 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
25c00 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
25c10 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
25c20 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
25c30 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
25c40 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
25c50 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
25c60 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
25c70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25c80 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
25c90 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
25ca0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
25cb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
25cc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
25cd0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25ce0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
25cf0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
25d00 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
25d10 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
25d20 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
25d30 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 5b   more than one [
25d40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25d50 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  ion] internally,
25d60 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e   then SQL.** fun
25d70 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
25d80 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
25d90 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61 62  y to each [datab
25da0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
25db0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
25dc0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
25dd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
25de0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
25df0 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20  e created.** or 
25e00 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  redefined..** Th
25e10 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
25e20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
25e30 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
25e40 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a  clusive of the .
25e50 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ** zero-terminat
25e60 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
25e70 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
25e80 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
25e90 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
25ea0 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
25eb0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
25ec0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
25ed0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
25ee0 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53  l result in an S
25ef0 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f  QLITE_ERROR erro
25f00 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  r..**.** The thi
25f10 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
25f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
25f30 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
25f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
25f50 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
25f60 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
25f70 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
25f80 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
25f90 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
25fa0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
25fb0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
25fc0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
25fd0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
25fe0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
25ff0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
26000 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
26010 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
26020 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
26030 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
26040 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
26050 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
26060 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26070 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
26080 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
26090 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
260a0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
260b0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
260c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
260d0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
260e0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
260f0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
26100 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
26110 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
26120 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
26130 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
26140 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
26150 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
26160 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
26170 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
26180 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
26190 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
261a0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
261b0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
261c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
261d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
261e0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
261f0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
26200 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
26210 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
26220 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
26230 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
26240 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
26250 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
26260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26270 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
26280 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20  re what.** text 
26290 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
262a0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
262b0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
262c0 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  d be.** [SQLITE_
262d0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
262e0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
262f0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
26300 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
26310 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
26320 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
26330 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
26340 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
26350 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
26360 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
26370 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
26380 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
26390 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
263a0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
263b0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
263c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
263d0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
263e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
263f0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
26400 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
26410 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
26420 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
26430 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
26440 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75  on of.** the xFu
26450 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  nc callback only
26460 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
26470 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
26480 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a   as the xStep.**
26490 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61   and xFinal para
264a0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
264b0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
264c0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
264d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
264e0 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  of xStep and xFi
264f0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
26500 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
26510 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
26520 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e  te an.** existin
26530 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  g SQL function o
26540 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
26550 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
26560 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
26570 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
26580 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
26590 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
265a0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
265b0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
265c0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
265d0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
265e0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
265f0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
26600 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
26610 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
26620 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
26630 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
26640 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
26650 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
26660 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
26670 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
26680 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
26690 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
266a0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  used..**.** INVA
266b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
266c0 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
266d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
266e0 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61  ion16()] interfa
266f0 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74  ce behaves exact
26700 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ly.**          l
26710 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  ike [sqlite3_cre
26720 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
26730 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
26740 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
26750 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
26760 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e  ts the zFunction
26770 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73  Name argument as
26780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
26790 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
267a0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
267b0 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
267c0 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   as a.**        
267d0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
267e0 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
267f0 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  F16106} A succes
26800 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
26810 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
26820 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26830 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
26840 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
26850 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
26860 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
26870 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
26880 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61 74  unctions in [dat
26890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
268a0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
268b0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
268c0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
268d0 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
268e0 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
268f0 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
26900 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20  ing a preferred 
26910 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
26920 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30   E..**.** {F1610
26930 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
26940 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26950 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26960 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
26970 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
26980 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46  eplaces the P, F
26990 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
269a0 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
269b0 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
269c0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
269d0 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
269e0 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  values..**.** {F
269f0 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
26a00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26a10 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
26a20 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
26a30 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
26a40 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
26a50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
26a60 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
26a70 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
26a80 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
26a90 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
26aa0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
26ab0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
26ac0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20  .**.** {F16118} 
26ad0 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65  Either F must be
26ae0 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
26af0 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
26b00 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20  r else F.**     
26b10 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c       is non-NULL
26b20 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
26b30 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65   NULL, otherwise
26b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
26b50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26b60 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
26b70 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20  F,S,L)] returns 
26b80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
26b90 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54  **.** {F16121} T
26ba0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26bb0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
26bc0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
26bd0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20  ils with an.**  
26be0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f          error co
26bf0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55  de of [SQLITE_BU
26c00 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69  SY] if there exi
26c10 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
26c20 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20  tements].**     
26c30 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20       associated 
26c40 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
26c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
26c60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d  ..**.** {F16124}
26c70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
26c80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
26c90 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  X,N,...)] interf
26ca0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
26cb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
26cc0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
26cd0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61  ITE_ERROR] if pa
26ce0 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69  rameter N (speci
26cf0 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  fying the number
26d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
26d10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
26d20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65   SQL function be
26d30 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20  ing registered) 
26d40 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
26d50 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
26d60 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
26d70 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20  .**.** {F16127} 
26d80 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
26d90 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
26da0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26db0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
26dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
26dd0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
26de0 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
26df0 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
26e00 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
26e10 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
26e20 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
26e30 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
26e40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
26e50 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
26e60 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
26e70 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {F16130} When N 
26e80 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
26e90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26ea0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
26eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
26ec0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
26ed0 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
26ee0 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
26ef0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
26f00 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69        named X wi
26f10 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  th any number of
26f20 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
26f30 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20  * {F16133} When 
26f40 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26f50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26f60 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
26f70 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
26f80 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
26f90 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
26fa0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
26fb0 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  X.**          an
26fc0 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65  d when one imple
26fd0 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e  mentation has N>
26fe0 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  =0 and the other
26ff0 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20   has N=(-1).**  
27000 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c          the impl
27010 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
27020 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20  a non-zero N is 
27030 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
27040 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {F16136} When c
27050 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
27060 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27070 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
27080 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
27090 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
270a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
270b0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
270c0 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
270d0 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
270e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
270f0 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
27100 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
27110 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
27120 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
27130 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
27140 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
27150 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
27160 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66  encoding is pref
27170 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
27180 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
27190 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
271a0 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
271b0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
271c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
271d0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
271e0 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
271f0 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  ializer.**      
27200 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77      function L w
27210 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  ill always be in
27220 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
27230 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
27240 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
27250 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
27260 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
27270 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32  s..**.** {F16142
27280 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
27290 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
272a0 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
272b0 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
272c0 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
272d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
272e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
272f0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
27300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
27310 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27320 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
27330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27340 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
27350 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
27360 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
27370 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
27380 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
27390 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
273a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  ird parameter ar
273b0 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63  e always [protec
273c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
273d0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
273e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
273f0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
27400 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
27410 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
27420 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
27430 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
27440 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
27450 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
27460 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
27470 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
27480 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
27490 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
274a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
274b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
274c0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
274d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
274e0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
274f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27500 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
27510 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
27520 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
27530 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
27540 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
27550 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
27560 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
27570 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
27580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
27590 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
275a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
275b0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
275c0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
275d0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
275e0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
275f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27600 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
27610 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10267}.**.** Th
27620 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
27630 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
27640 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
27650 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
27660 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
27670 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
27680 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
27690 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
276a0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
276b0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
276c0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
276d0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
276e0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
276f0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
27700 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
27710 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27720 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
27730 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
27740 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
27750 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27760 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
27770 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27780 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
27790 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
277a0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
277b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
277c0 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e  EF: Obsolete Fun
277d0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
277e0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
277f0 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74   all now obsolet
27800 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  e.  In order to 
27810 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
27820 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27830 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
27840 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65  ode, we continue
27850 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74   to support.** t
27860 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
27870 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65   However, new de
27880 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63  velopment projec
27890 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ts should avoid.
278a0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
278b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
278c0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
278d0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
278e0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
278f0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
27900 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
27910 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68  tell you want th
27920 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ey do..*/.int sq
27930 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27940 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
27950 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  ntext*);.int sql
27960 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
27970 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
27980 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
27990 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
279a0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
279b0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
279c0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
279d0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64  over(void);.void
279e0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
279f0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69  cleanup(void);.i
27a00 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
27a10 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
27a20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
27a30 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
27a40 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
27a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27a60 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
27a70 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
27a80 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d   Values {F15100}
27a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
27aa0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
27ab0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
27ac0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
27ad0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
27ae0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
27af0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
27b00 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
27b10 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
27b20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
27b30 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
27b40 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
27b50 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
27b60 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
27b70 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
27b80 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
27b90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27ba0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
27bb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27bc0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
27bd0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
27be0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
27bf0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
27c00 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
27c10 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
27c20 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
27c30 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
27c40 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
27c50 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
27c60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27c70 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
27c80 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
27c90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
27ca0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
27cb0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
27cc0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
27cd0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
27ce0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
27cf0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
27d00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27d10 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
27d20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
27d30 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
27d40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27d50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
27d60 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
27d70 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
27d80 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
27d90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27da0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
27db0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
27dc0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
27dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27de0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
27df0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
27e00 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  onding .** [sqli
27e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20  te3_column_blob 
27e20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
27e30 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63  _* routines] exc
27e40 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65  ept that .** the
27e50 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
27e60 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
27e70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27e80 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  ue] object point
27e90 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  er.** instead of
27ea0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
27eb0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
27ec0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
27ed0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   number..**.** T
27ee0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27ef0 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
27f00 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
27f10 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  TF16 string.** i
27f20 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
27f30 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
27f40 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68  ost machine.  Th
27f50 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
27f60 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
27f70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
27f80 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
27f90 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
27fa0 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61   UTF16 strings a
27fb0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
27fc0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
27fd0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
27fe0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
27ff0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
28000 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
28010 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
28020 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
28030 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
28040 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
28050 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
28060 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
28070 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
28080 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
28090 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
280a0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
280b0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
280c0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
280d0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
280e0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
280f0 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ds if the value 
28100 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
28110 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
28120 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
28130 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
28140 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65  done.  Otherwise
28150 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
28160 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20  ccurs.  The .** 
28170 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
28180 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
28190 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
281a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
281b0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
281c0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
281d0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
281e0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
281f0 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  t.** is returned
28200 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
28210 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
28220 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28230 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
28240 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28250 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
28260 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
28270 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
28280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
28290 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
282a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
282b0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
282c0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
282d0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
282e0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20  lue_text16()].  
282f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28300 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
28310 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
28320 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
28330 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
28340 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
28350 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28360 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
28370 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  **.**.** INVARIA
28380 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  NTS:.**.** {F151
28390 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
283a0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
283b0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
283c0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
283d0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
283e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
283f0 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c 6f  ect V into a blo
28400 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  b and then retur
28410 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
28420 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
28430 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
28440 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d 20  .**.** {F15106} 
28450 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28460 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74  ue_bytes(V)] int
28470 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28480 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
28490 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
284a0 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74  n the blob or st
284b0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
284c0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
284d0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
284e0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
284f0 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
28500 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
28510 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
28520 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
28530 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
28540 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
28550 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
28560 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  _text(V)]..**.**
28570 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b 73   {F15109} The [s
28580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
28590 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61  es16(V)] interfa
285a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
285b0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
285c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
285d0 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
285e0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
285f0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
28600 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
28610 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
28620 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
28630 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
28640 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
28650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28660 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20  xt16(V)],.**    
28670 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
28680 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29  alue_text16be(V)
28690 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ], or [sqlite3_v
286a0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
286b0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 32  ]..**.** {F15112
286c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
286d0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20  alue_double(V)] 
286e0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
286f0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28700 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
28710 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28720 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f  ect V into a flo
28730 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
28740 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
28750 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
28760 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a   of that value..
28770 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20 54  **.** {F15115} T
28780 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28790 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66  e_int(V)] interf
287a0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
287b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
287c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
287d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
287e0 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
287f0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
28800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
28810 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
28820 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
28830 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
28840 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  15118} The [sqli
28850 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
28860 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
28870 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
28880 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
28890 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
288a0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
288b0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
288c0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
288d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
288e0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
288f0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
28900 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  5121} The [sqlit
28910 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
28920 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28930 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
28940 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
28950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28960 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
28970 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28980 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20  TF-8 .**        
28990 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
289a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
289b0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
289c0 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54 68  *.** {F15124} Th
289d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
289e0 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
289f0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28a00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
28a10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28a20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28a30 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
28a40 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
28a50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
28a60 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
28a70 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
28a80 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
28a90 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
28aa0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
28ab0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
28ac0 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
28ad0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
28ae0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
28af0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28b00 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
28b10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28b20 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
28b30 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
28b40 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
28b50 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
28b60 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
28b70 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
28b80 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
28b90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
28ba0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
28bb0 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
28bc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28bd0 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
28be0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28bf0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
28c00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28c10 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
28c20 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28c30 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
28c40 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
28c50 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
28c60 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
28c70 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
28c80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
28c90 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
28ca0 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65 20  ** {F15133} The 
28cb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28cc0 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
28cd0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
28ce0 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
28cf0 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
28d00 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
28d10 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
28d20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
28d30 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
28d40 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
28d50 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
28d60 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
28d70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28d80 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ect V..**.** {F1
28d90 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
28da0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
28db0 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
28dc0 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
28dd0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
28de0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28df0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
28e00 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
28e10 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
28e20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
28e30 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
28e40 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
28e50 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
28e60 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
28e70 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
28e80 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
28e90 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
28ea0 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
28eb0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
28ec0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
28ed0 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
28ee0 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
28ef0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
28f00 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
28f10 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20   the [protected 
28f20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28f30 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
28f40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
28f50 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
28f60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
28f70 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
28f80 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
28f90 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
28fa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
28fb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
28fc0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
28fd0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
28fe0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
28ff0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
29000 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
29010 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
29020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29030 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
29040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
29050 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
29060 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
29070 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
29080 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
29090 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
290a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
290b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
290c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
290d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
290e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
290f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
29100 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29120 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
29130 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29140 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
29150 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
29160 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
29170 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
29180 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
29190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
291a0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
291b0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
291c0 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a  t {F16210}.**.**
291d0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
291e0 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
291f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
29200 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
29210 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
29220 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
29230 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
29240 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72  te.  .** The fir
29250 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
29260 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29270 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20  ntext() routine 
29280 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20  is.** is called 
29290 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
292a0 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
292b0 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
292c0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  tes of memory.**
292d0 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f   zeros that memo
292e0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
292f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
29300 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  .** On second an
29310 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
29320 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
29330 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29340 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
29350 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
29360 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65 20  tion index, the 
29370 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
29380 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
29390 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
293a0 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  * of the aggrega
293b0 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72  te can use the r
293c0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
293d0 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
293e0 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  a..**.** SQLite 
293f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
29400 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  ees the allocate
29410 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68  d buffer when th
29420 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
29430 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
29440 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
29450 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
29460 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
29470 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  e .** [sqlite3_c
29480 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
29490 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
294a0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
294b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
294c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
294d0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
294e0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
294f0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
29500 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
29510 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
29520 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
29530 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
29540 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
29550 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
29560 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
29570 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
29580 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20  ** {F16211} The 
29590 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
295a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   of [sqlite3_agg
295b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
295c0 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ,N)] for.**     
295d0 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61       a particula
295e0 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e  r instance of an
295f0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
29600 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69  ion (for a parti
29610 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20  cular.**        
29620 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75    context C) cau
29630 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c  ses SQLite to al
29640 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65 73  location N bytes
29650 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20   of memory,.**  
29660 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61          zero tha
29670 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
29680 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
29690 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 0a  o the allocated.
296a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
296b0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  ry..**.** {F1621
296c0 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  3} If a memory a
296d0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
296e0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a  occurs during.**
296f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
29700 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29710 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20  text(C,N)] then 
29720 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
29730 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46  urns 0..**.** {F
29740 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e  16215} Second an
29750 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  d subsequent inv
29760 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20  ocations of.**  
29770 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
29780 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
29790 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65  xt(C,N)] for the
297a0 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f   same context po
297b0 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20  inter C.**      
297c0 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e      ignore the N
297d0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
297e0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
297f0 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  to the same.**  
29800 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66          block of
29810 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
29820 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e   by the first in
29830 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
29840 7b 46 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d  {F16217} The mem
29850 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
29860 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
29870 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
29880 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
29890 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
298a0 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74  reed on the next
298b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
298c0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20  3_reset()].**   
298d0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
298e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66  e3_finalize()] f
298f0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
29900 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74   statement] cont
29910 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  aining.**       
29920 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65     the aggregate
29930 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
29940 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78  ated with contex
29950 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  t C..*/.void *sq
29960 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29970 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
29980 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
29990 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
299a0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
299b0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  a For Functions 
299c0 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16240}.**.** T
299d0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
299e0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
299f0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
29a00 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
29a10 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
29a20 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
29a30 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
29a40 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
29a50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29a60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
29a70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
29a80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
29a90 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
29aa0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
29ab0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
29ac0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
29ad0 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
29ae0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
29af0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
29b00 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
29b10 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
29b20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
29b30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29b40 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
29b50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
29b60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33  S:.**.** {F16243
29b70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
29b80 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74  ser_data(C)] int
29b90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29ba0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
29bb0 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74           P point
29bc0 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
29bd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29be0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
29bf0 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
29c00 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
29c10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29c20 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
29c30 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
29c40 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
29c50 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
29c60 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
29c70 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20  with .**        
29c80 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65    [sqlite3_conte
29c90 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  xt] C..*/.void *
29ca0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
29cb0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
29cc0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
29cd0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
29ce0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
29cf0 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 35 30 7d  nctions {F16250}
29d00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
29d10 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
29d20 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
29d30 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
29d40 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
29d50 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
29d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
29d70 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
29d80 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
29d90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29da0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
29db0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29dc0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
29dd0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
29de0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
29df0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
29e00 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
29e10 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ction..**.** INV
29e20 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
29e30 46 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c  F16253} The [sql
29e40 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
29e50 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72  handle(C)] inter
29e60 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
29e70 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
29e80 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72         D pointer
29e90 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
29ea0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29eb0 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
29ec0 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
29ed0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
29ee0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
29ef0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
29f00 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
29f10 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
29f20 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
29f30 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
29f40 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  th .**          
29f50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
29f60 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ] C..*/.sqlite3 
29f70 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
29f80 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
29f90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
29fa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
29fb0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
29fc0 79 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a  y Data {F16270}.
29fd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
29fe0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
29ff0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2a000 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2a010 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2a020 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20  ciate meta-data 
2a030 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
2a040 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
2a050 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
2a060 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
2a070 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2a080 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
2a090 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
2a0a0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
2a0b0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
2a0c0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
2a0d0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61  sociated meta-da
2a0e0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2a0f0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2a100 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2a110 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2a120 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2a130 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2a140 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2a150 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2a160 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2a170 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2a180 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2a190 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61  eta-data associa
2a1a0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2a1b0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2a1c0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2a1d0 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2a1e0 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2a1f0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2a200 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2a210 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2a220 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2a230 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2a240 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2a250 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2a260 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2a270 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2a280 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2a290 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2a2a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
2a2b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2a2c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2a2d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2a2e0 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73  meta-data.** ass
2a2f0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2a300 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a310 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2a320 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2a330 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2a340 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a350 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a360 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d  ..** If no meta-
2a370 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
2a380 65 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  er been set for 
2a390 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d  the Nth.** argum
2a3a0 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
2a3b0 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
2a3c0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2a3d0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
2a3e0 2a 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  ** has changed s
2a3f0 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
2a400 74 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e  ta was set, then
2a410 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2a420 64 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e  data().** return
2a430 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a440 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2a450 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2a460 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
2a470 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  s the meta-data.
2a480 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2a490 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
2a4a0 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64  er as the meta-d
2a4b0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
2a4c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
2a4d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a4e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a4f0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
2a500 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2a510 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2a520 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
2a530 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
2a540 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
2a550 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20  stroyed. .** If 
2a560 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
2a570 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2a580 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2a590 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  r .** function g
2a5a0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
2a5b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2a5c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2a5d0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
2a5e0 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  a-data when the 
2a5f0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
2a600 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2a610 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
2a620 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
2a630 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
2a640 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
2a650 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
2a660 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
2a670 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
2a680 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
2a690 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79  a-data on.** any
2a6a0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2a6b0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2a6c0 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c  y time.  The onl
2a6d0 79 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69  y guarantee.** i
2a6e0 73 20 74 68 61 74 20 74 68 65 20 64 65 73 74 72  s that the destr
2a6f0 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
2a700 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
2a710 6d 65 74 61 64 61 74 61 20 69 73 0a 2a 2a 20 64  metadata is.** d
2a720 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ropped..**.** In
2a730 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
2a740 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2a750 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2a760 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2a770 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2a780 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2a790 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2a7a0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2a7b0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2a7c0 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
2a7d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2a7e0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2a7f0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2a800 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2a810 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2a820 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2a830 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2a840 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2a850 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  272} The [sqlite
2a860 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
2a870 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2a880 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2a890 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d  **          to m
2a8a0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2a8b0 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
2a8c0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2a8d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2a8e0 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20            whose 
2a8f0 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72  context is C, or
2a900 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
2a910 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73  s no metadata as
2a920 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20  sociated.**     
2a930 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70       with that p
2a940 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2a950 7b 46 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71  {F16274} The [sq
2a960 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2a970 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65  a(C,N,P,D)] inte
2a980 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20  rface assigns a 
2a990 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
2a9a0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74       pointer P t
2a9b0 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  o the Nth parame
2a9c0 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
2a9d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e  unction with con
2a9e0 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
2a9f0 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37   C..**.** {F1627
2aa00 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  6} SQLite will i
2aa10 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2aa20 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
2aa30 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
2aa40 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20            which 
2aa50 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  is the metadata 
2aa60 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77  pointer P follow
2aa70 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ing a call to.**
2aa80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2aa90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2aaa0 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51  ,N,P,D)] when SQ
2aab0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2aac0 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  old.**          
2aad0 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a  the metadata..**
2aae0 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c  .** {F16277} SQL
2aaf0 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2ab00 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  ld metadata for 
2ab10 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2ab20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
2ab30 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76        when the v
2ab40 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72  alue of that par
2ab50 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a  ameter changes..
2ab60 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57  **.** {F16278} W
2ab70 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  hen [sqlite3_set
2ab80 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
2ab90 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  )] is invoked, t
2aba0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2abb0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c            is cal
2abc0 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f  led for any prio
2abd0 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  r metadata assoc
2abe0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
2abf0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2ac00 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2ac10 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72   C and parameter
2ac20 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37   N..**.** {F1627
2ac30 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  9} SQLite will c
2ac40 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20  all destructors 
2ac50 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61  for any metadata
2ac60 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a   it is holding.*
2ac70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20  *          in a 
2ac80 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70  particular [prep
2ac90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2aca0 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a  S when either.**
2acb0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2acc0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20  e3_reset(S)] or 
2acd0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ace0 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
2acf0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ad00 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
2ad10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2ad20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
2ad30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2ad40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ad50 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
2ad60 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
2ad70 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
2ad80 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
2ad90 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
2ada0 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
2adb0 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a  ior {F10280}.**.
2adc0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2add0 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74  cial value for t
2ade0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2adf0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2ae00 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2ae10 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2ae20 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2ae30 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2ae40 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
2ae50 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
2ae60 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
2ae70 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
2ae80 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
2ae90 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
2aea0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
2aeb0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
2aec0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2aed0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
2aee0 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  The .** SQLITE_T
2aef0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
2af00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2af10 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
2af20 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
2af30 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
2af40 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
2af50 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
2af60 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2af70 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
2af80 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
2af90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
2afa0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
2afb0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
2afc0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
2afd0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
2afe0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
2aff0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
2b000 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
2b010 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2b020 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
2b030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
2b040 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
2b050 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2b060 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
2b070 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
2b080 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2b090 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
2b0a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b0b0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
2b0c0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
2b0d0 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a  ction {F16400}.*
2b0e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2b0f0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
2b100 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
2b110 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
2b120 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
2b130 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2b140 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
2b150 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
2b160 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b170 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2b180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2b190 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
2b1a0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2b1b0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
2b1c0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
2b1d0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
2b1e0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
2b1f0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2b200 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
2b210 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
2b220 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
2b230 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
2b240 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
2b250 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
2b260 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
2b270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b280 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2b290 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
2b2a0 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
2b2b0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2b2c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2b2d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2b2e0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
2b2f0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2b300 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2b310 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2b320 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2b330 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
2b340 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
2b350 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
2b360 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
2b370 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
2b380 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
2b390 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
2b3a0 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68  arameter. .** Th
2b3b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b3c0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2b3d0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2b3e0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2b3f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2b400 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2b410 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2b420 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2b430 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2b440 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2b450 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2b460 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2b470 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
2b480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b490 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2b4a0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2b4b0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2b4c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2b4d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2b4e0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2b4f0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2b500 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2b510 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2b520 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2b530 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2b540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b550 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2b560 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2b570 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2b580 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2b590 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2b5a0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2b5b0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2b5c0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2b5d0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2b5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b5f0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2b600 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2b610 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2b620 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2b630 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
2b640 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2b650 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2b660 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2b670 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2b680 20 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74 65   as UTF8. SQLite
2b690 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2b6a0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2b6b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b6c0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31 36  ror16() as UTF16
2b6d0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2b6e0 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68  te order.  If th
2b6f0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2b700 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2b710 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2b720 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2b730 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2b740 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2b750 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2b760 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2b770 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2b780 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2b790 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2b7a0 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70  * If the third p
2b7b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b7c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b7d0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2b7e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2b7f0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
2b800 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2b810 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
2b820 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2b830 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
2b840 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2b850 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
2b860 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  age..** The sqli
2b870 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b880 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2b890 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2b8a0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2b8b0 20 61 20 63 6f 70 79 20 70 72 69 76 61 74 65 20   a copy private 
2b8c0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2b8d0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2b8e0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2b8f0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2b900 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2b910 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2b920 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2b930 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2b940 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2b950 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
2b960 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b970 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2b980 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2b990 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2b9a0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2b9b0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2b9c0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2b9d0 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
2b9e0 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2b9f0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2ba00 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
2ba10 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2ba20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ba30 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2ba40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2ba50 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2ba60 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2ba70 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2ba80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ba90 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
2baa0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2bab0 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  Lite.** to throw
2bac0 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61   an error indica
2bad0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2bae0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2baf0 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72   long.** to repr
2bb00 65 73 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  esent.  The sqli
2bb10 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
2bb20 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
2bb30 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2bb40 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
2bb50 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ion indicating t
2bb60 68 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d  hat the a.** mem
2bb70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2bb80 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ailed..**.** The
2bb90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bba0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
2bbb0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2bbc0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2bbd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2bbe0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2bbf0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
2bc00 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2bc10 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2bc20 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2bc30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2bc40 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
2bc50 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2bc60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2bc70 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2bc80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2bc90 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2bca0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2bcb0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2bcc0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2bcd0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2bce0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2bcf0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
2bd00 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2bd10 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2bd20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bd30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bd40 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2bd50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2bd60 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2bd70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2bd80 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74  t16(), .** sqlit
2bd90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2bda0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
2bdb0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2bdc0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2bdd0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
2bde0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
2bdf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2be00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2be10 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
2be20 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
2be30 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
2be40 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2be50 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
2be60 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
2be70 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
2be80 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
2be90 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
2bea0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2beb0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2bec0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2bed0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2bee0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2bef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2bf00 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2bf10 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
2bf20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2bf30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2bf40 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2bf50 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2bf60 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2bf70 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
2bf80 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2bf90 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  er .** through t
2bfa0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2bfb0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74  aracter..** If t
2bfc0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2bfd0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2bfe0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2bff0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
2c000 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
2c010 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
2c020 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2c030 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
2c040 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2c050 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2c060 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
2c070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c080 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
2c090 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
2c0a0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2c0b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2c0c0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2c0d0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2c0e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2c0f0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2c100 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2c110 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2c120 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2c130 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2c140 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62  the text or blob
2c150 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2c160 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2c170 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2c180 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2c190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2c1a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c1b0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2c1c0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2c1d0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2c1e0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2c1f0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
2c200 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  C, then.** SQLit
2c210 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2c220 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20  he text or blob 
2c230 72 65 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61  result is consta
2c240 6e 74 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20  nt space and.** 
2c250 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68  does not copy th
2c260 65 20 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20  e space or call 
2c270 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65  a destructor whe
2c280 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2c290 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2c2a0 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
2c2b0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2c2c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2c2d0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2c2e0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2c2f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2c300 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2c310 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2c320 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
2c330 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
2c340 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
2c350 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
2c360 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
2c370 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2c380 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
2c390 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
2c3a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2c3b0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2c3c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2c3d0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2c3e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c3f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c400 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2c410 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2c420 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c430 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2c440 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2c450 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
2c460 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c470 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
2c480 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2c490 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2c4a0 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c  .** so that [sql
2c4b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
2c4c0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
2c4d0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
2c4e0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
2c4f0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
2c500 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2c510 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
2c520 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
2c530 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c540 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c550 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
2c560 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
2c570 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c580 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c590 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
2c5a0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
2c5b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2c5c0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
2c5d0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
2c5e0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2c5f0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
2c600 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
2c610 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
2c620 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2c630 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
2c640 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2c650 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c660 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
2c670 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
2c680 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2c690 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
2c6a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2c6b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
2c6c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2c6d0 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64 65 66  {F16403} The def
2c6e0 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75  ault return valu
2c6f0 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66  e from any SQL f
2c700 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e  unction is NULL.
2c710 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20  .**.** {F16406} 
2c720 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2c730 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
2c740 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2c750 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2c760 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2c770 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2c780 74 6f 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61  to be a blob tha
2c790 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20  t is N bytes.** 
2c7a0 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67           in leng
2c7b0 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74  th and with cont
2c7c0 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ent pointed to b
2c7d0 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  y V..**.** {F164
2c7e0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2c7f0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43  _result_double(C
2c800 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
2c810 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2c820 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2c830 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2c840 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61  C to be the floa
2c850 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2c860 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31   V..**.** {F1641
2c870 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2c880 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56  result_error(C,V
2c890 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2c8a0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
2c8b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
2c8c0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2c8d0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
2c8e0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
2c8f0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
2c900 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2c910 61 6e 64 20 61 20 55 54 46 38 20 65 72 72 6f 72  and a UTF8 error
2c920 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20   message copied 
2c930 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
2c940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
2c950 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20  st zero byte or 
2c960 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
2c970 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
2c980 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
2c990 46 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c  F16415} The [sql
2c9a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c9b0 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  r16(C,V,N)] inte
2c9c0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c9d0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
2c9e0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
2c9f0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
2ca00 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
2ca10 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
2ca20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2ca30 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
2ca40 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2ca50 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61  rder error messa
2ca60 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ge.**          c
2ca70 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
2ca80 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2ca90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20  o terminator or 
2caa0 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a  until N bytes.**
2cab0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65            are re
2cac0 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
2cad0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2cae0 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2caf0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2cb00 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61  obig(C)] interfa
2cb10 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2cb20 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2cb30 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
2cb40 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2cb50 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2cb60 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
2cb70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2cb80 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20  _TOOBIG] and an 
2cb90 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
2cba0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
2cbb0 20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73   {F16421} The [s
2cbc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2cbd0 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e  ror_nomem(C)] in
2cbe0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2cbf0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2cc00 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2cc10 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
2cc20 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2cc30 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2cc40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
2cc50 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64  QLITE_NOMEM] and
2cc60 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2cc70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2cc80 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68  *.** {F16424} Th
2cc90 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2cca0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45  t_error_code(C,E
2ccb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2ccc0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
2ccd0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
2cce0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2ccf0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
2cd00 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
2cd10 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20  r code E..**    
2cd20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20        The error 
2cd30 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20  message text is 
2cd40 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
2cd50 20 7b 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73   {F16427} The [s
2cd60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2cd70 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  t(C,V)] interfac
2cd80 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2cd90 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cda0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2cdb0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33  on C to be the 3
2cdc0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61  2-bit integer va
2cdd0 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
2cde0 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  6430} The [sqlit
2cdf0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2ce00 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2ce10 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2ce20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2ce30 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2ce40 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d   C to be the 64-
2ce50 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
2ce60 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
2ce70 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
2ce80 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d  _result_null(C)]
2ce90 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2cea0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2ceb0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2cec0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2ced0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2cee0 7b 46 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71  {F16436} The [sq
2cef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2cf00 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  t(C,V,N,D)] inte
2cf10 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2cf20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2cf30 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2cf40 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
2cf50 68 65 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  he UTF8 string.*
2cf60 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20  *          V up 
2cf70 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2cf80 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
2cf90 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
2cfa0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
2cfb0 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
2cfc0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
2cfd0 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68  *.** {F16439} Th
2cfe0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2cff0 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2d000 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2d010 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2d020 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2d030 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2d040 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2d050 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2d060 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
2d070 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2d080 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2d090 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2d0a0 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
2d0b0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
2d0c0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
2d0d0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
2d0e0 46 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16442} The [sql
2d0f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d100 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
2d110 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2d120 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d130 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2d140 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2d150 65 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d  e the UTF16 big-
2d160 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
2d170 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
2d180 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2d190 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20   if N is.**     
2d1a0 20 20 20 20 20 69 73 20 6e 65 67 61 74 69 76 65       is negative
2d1b0 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
2d1c0 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20  bytes or V if N 
2d1d0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
2d1e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20  .**.** {F16445} 
2d1f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2d200 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
2d210 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2d220 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2d230 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2d240 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2d250 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2d260 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  F16 little-endia
2d270 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2d280 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2d290 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2d2a0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2d2b0 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
2d2c0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
2d2d0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
2d2e0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
2d2f0 46 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c  F16448} The [sql
2d300 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2d310 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
2d320 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2d330 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2d340 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2d350 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75 6e 70 72  on C to be [unpr
2d360 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d370 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
2d380 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
2d390 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54 68 65 20  ** {F16451} The 
2d3a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d3b0 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
2d3c0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2d3d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d3e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2d3f0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2d400 65 20 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62  e an N-byte blob
2d410 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
2d420 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54 68  *.** {F16454} Th
2d430 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2d440 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
2d450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2d460 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
2d470 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
2d480 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
2d490 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
2d4a0 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
2d4b0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
2d4c0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2d4d0 7b 46 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {F16457} If the 
2d4e0 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
2d4f0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2d500 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
2d510 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
2d520 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2d530 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
2d540 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
2d550 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
2d560 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2d570 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2d580 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
2d590 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
2d5a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d5b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2d5c0 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
2d5d0 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
2d5e0 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
2d5f0 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
2d600 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
2d610 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
2d620 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
2d630 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
2d640 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
2d650 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
2d660 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49 66 20 74  ** {F16460} If t
2d670 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
2d680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2d690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2d6a0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
2d6b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d6c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2d6d0 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
2d6e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2d6f0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2d700 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d710 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2d720 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
2d730 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d740 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d750 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
2d760 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
2d770 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2d780 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
2d790 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
2d7a0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2d7b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d7c0 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
2d7d0 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
2d7e0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33  y..**.** {F16463
2d7f0 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
2d800 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
2d810 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2d820 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
2d830 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2d840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d850 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
2d860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d870 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
2d880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d8a0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
2d8b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2d8c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d8d0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2d8e0 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
2d8f0 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
2d900 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
2d910 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
2d920 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
2d930 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
2d940 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  n .**          S
2d950 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2d960 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2d970 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73   D with V as its
2d980 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a   only argument.*
2d990 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
2d9a0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2d9b0 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65  with the V value
2d9c0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2d9d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2d9e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d9f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2da00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2da10 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2da20 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
2da30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2da40 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
2da50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2da60 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
2da70 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2da80 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2da90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2daa0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
2dab0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2dac0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2dad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2dae0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
2daf0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2db00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2db10 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
2db20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2db30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2db40 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
2db50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2db60 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2db70 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
2db80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2db90 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2dba0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2dbb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dbc0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2dbd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2dbe0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
2dbf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2dc00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2dc10 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
2dc20 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2dc30 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
2dc40 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2dc50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2dc60 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2dc70 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2dc80 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2dc90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2dca0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2dcb0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2dcc0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2dcd0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2dce0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2dcf0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2dd00 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
2dd10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2dd20 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2dd30 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2dd40 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2dd50 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
2dd60 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2dd70 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
2dd80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2dd90 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2dda0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2ddb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ddc0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
2ddd0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
2dde0 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a  es {F16600}.**.*
2ddf0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2de00 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
2de10 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
2de20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
2de30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  .** [sqlite3*] h
2de40 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20  andle specified 
2de50 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2de60 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  ument. .**.** Th
2de70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
2de80 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
2de90 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
2dea0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
2deb0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
2dec0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ded0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
2dee0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2def0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
2df00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
2df10 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2df20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2df30 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
2df40 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
2df50 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
2df60 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2df70 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
2df80 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
2df90 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
2dfa0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
2dfb0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
2dfc0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
2dfd0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2dfe0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
2dff0 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
2e000 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
2e010 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
2e020 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
2e030 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
2e040 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
2e050 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
2e060 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62  dian or UTF-16 b
2e070 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  ig-endian respec
2e080 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
2e090 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
2e0a0 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
2e0b0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2e0c0 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
2e0d0 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
2e0e0 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
2e0f0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
2e100 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
2e110 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69  gs.** of UTF16 i
2e120 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2e130 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e order of the h
2e140 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
2e150 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
2e160 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69   the user suppli
2e170 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  ed routine must 
2e180 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2e190 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65   fifth.** argume
2e1a0 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55  nt.  If it is NU
2e1b0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
2e1c0 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
2e1d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
2e1e0 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
2e1f0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
2e200 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
2e210 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65  e)..** Each time
2e220 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e230 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e  .** supplied fun
2e240 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
2e250 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61  , it is passed a
2e260 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
2e270 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  d* passed as.** 
2e280 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2e290 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2e2a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2e2b0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2e2c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e2d0 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73  16() as its firs
2e2e0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
2e2f0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
2e300 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2e310 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
2e320 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
2e330 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
2e340 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
2e350 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
2e360 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
2e370 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
2e380 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
2e390 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
2e3a0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2e3b0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
2e3c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
2e3d0 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
2e3e0 20 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69   {END} The appli
2e3f0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
2e400 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
2e410 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
2e420 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
2e430 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a   or positive if.
2e440 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72  ** the first str
2e450 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2e460 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
2e470 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2e480 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67  second.** string
2e490 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
2e4a0 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
2e4b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
2e4c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2e4d0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
2e4e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e4f0 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
2e500 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
2e510 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
2e520 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
2e530 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
2e540 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
2e550 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
2e560 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
2e570 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
2e580 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
2e590 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
2e5a0 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
2e5b0 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
2e5c0 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
2e5d0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e5e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
2e5f0 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  .** Collations a
2e600 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
2e610 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76  n.** they are ov
2e620 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
2e630 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  r calls to the c
2e640 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2e650 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f  n functions.** o
2e660 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  r when the [sqli
2e670 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68  te3*] database h
2e680 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20  andle is closed 
2e690 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2e6a0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lose()]..**.** I
2e6b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2e6c0 20 7b 46 31 36 36 30 33 7d 20 41 20 73 75 63 63   {F16603} A succ
2e6d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74  essful call to t
2e6e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2e6f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e700 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2e710 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66  E,P,F,D)] interf
2e720 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
2e730 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69  registers functi
2e740 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70  on F as the comp
2e750 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
2e760 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  used to.**      
2e770 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f      implement co
2e780 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61  llation X on [da
2e790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e7a0 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20  n] B for.**     
2e7b0 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68       databases h
2e7c0 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45  aving encoding E
2e7d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d  ..**.** {F16604}
2e7e0 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61   SQLite understa
2e7f0 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65  nds the X parame
2e800 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
2e810 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2e820 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2e830 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73  B,X,E,P,F,D)] as
2e840 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2e850 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
2e860 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77  TF-8 string in w
2e870 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e  hich case is ign
2e880 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63  ored for ASCII c
2e890 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a  haracters and.**
2e8a0 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67            is sig
2e8b0 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e  nificant for non
2e8c0 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72  -ASCII character
2e8d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36  s..**.** {F16606
2e8e0 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c  } Successive cal
2e8f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
2e900 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e910 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
2e920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
2e930 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
2e940 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20  s for B, X, and 
2e950 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f  E, override prio
2e960 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  r values.**     
2e970 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e       of P, F, an
2e980 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  d D..**.** {F166
2e990 30 39 7d 20 54 68 65 20 64 65 73 74 72 75 63 74  09} The destruct
2e9a0 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33  or D in [sqlite3
2e9b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e9c0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
2e9d0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
2e9e0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
2e9f0 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  it is called wit
2ea00 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
2ea10 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2ea20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63    collating func
2ea30 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
2ea40 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
2ea50 20 7b 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c   {F16612} A coll
2ea60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
2ea70 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69  s dropped when i
2ea80 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e  t is overloaded.
2ea90 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20  .**.** {F16615} 
2eaa0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
2eab0 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
2eac0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2ead0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
2eae0 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73           is clos
2eaf0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2eb00 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2eb10 2a 20 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70  * {F16618} The p
2eb20 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c  ointer P in [sql
2eb30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2eb40 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2eb50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
2eb60 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72     is passed thr
2eb70 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
2eb80 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
2eb90 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  he comparison.**
2eba0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
2ebb0 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62  on F for all sub
2ebc0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2ebd0 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20  ons of F..**.** 
2ebe0 7b 46 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20  {F16621} A call 
2ebf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2ec00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58  te_collation(B,X
2ec10 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63  ,E,P,F)] is exac
2ec20 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
2ec30 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61  the same as a ca
2ec40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2ec50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2ec60 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20  v2()] with.**   
2ec70 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2ec80 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61  parameters and a
2ec90 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72   NULL destructor
2eca0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d  ..**.** {F16624}
2ecb0 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71   Following a [sq
2ecc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ecd0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
2ece0 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  P,F,D)],.**     
2ecf0 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73       SQLite uses
2ed00 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
2ed10 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
2ed20 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73  ll text comparis
2ed30 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
2ed40 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61  perations on [da
2ed50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ed60 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c  n] B on text val
2ed70 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  ues that.**     
2ed80 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c       use the col
2ed90 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
2eda0 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46  name X..**.** {F
2edb0 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
2edc0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2edd0 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
2ede0 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
2edf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
2ee00 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ee10 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
2ee20 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
2ee30 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
2ee40 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
2ee50 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
2ee60 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
2ee70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ee80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
2ee90 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
2eea0 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68  *.** {F16630} Wh
2eeb0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
2eec0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
2eed0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
2eee0 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
2eef0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
2ef00 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
2ef10 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
2ef20 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
2ef30 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
2ef40 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
2ef50 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2ef60 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2ef70 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
2ef80 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
2ef90 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
2efa0 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
2efb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2efc0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
2efd0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2efe0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2eff0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2f000 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
2f010 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2f020 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2f030 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
2f040 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2f050 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2f060 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2f070 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2f080 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2f090 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2f0a0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2f0b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2f0c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2f0d0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
2f0e0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
2f0f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f100 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2f110 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2f120 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2f130 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2f140 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2f150 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2f160 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2f170 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2f180 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2f190 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2f1a0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2f1b0 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a  lbacks {F16700}.
2f1c0 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68  **.** To avoid h
2f1d0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
2f1e0 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
2f1f0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
2f200 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
2f210 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
2f220 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
2f230 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
2f240 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
2f250 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61  e.** database ha
2f260 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65  ndle to be calle
2f270 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
2f280 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2f290 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a  n sequence is.**
2f2a0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2f2b0 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   If the function
2f2c0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2f2d0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2f2e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f2f0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2f300 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2f310 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2f320 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2f330 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2f340 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2f350 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33  n UTF-8. {F16703
2f360 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  } If sqlite3_col
2f370 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2f380 29 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e  ) is used, the n
2f390 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73  ames.** are pass
2f3a0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2f3b0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
2f3c0 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c  yte order. A cal
2f3d0 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66  l to either.** f
2f3e0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
2f3f0 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61   any existing ca
2f400 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
2f410 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
2f420 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2f430 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
2f440 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
2f450 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
2f460 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2f470 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f480 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
2f490 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2f4a0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
2f4b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2f4c0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
2f4d0 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68 65  .** handle.  The
2f4e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2f4f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2f500 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
2f510 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2f520 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2f530 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2f540 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61  e most.** desira
2f550 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
2f560 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2f570 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2f580 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75  ired..** The fou
2f590 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2f5a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2f5b0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
2f5c0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
2f5d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2f5e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2f5f0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2f600 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2f610 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2f620 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2f630 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2f640 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2f650 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2f660 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f670 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2f680 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2f690 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32  S:.**.** {F16702
2f6a0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2f6b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f6c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2f6d0 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
2f6e0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2f6f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f700 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
2f710 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
2f720 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f730 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
2f740 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
2f750 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
2f760 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
2f770 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
2f780 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
2f790 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
2f7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
2f7b0 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
2f7c0 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
2f7d0 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
2f7e0 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45 61 63 68  ** {F16704} Each
2f7f0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2f800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
2f810 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
2f820 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2f830 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2f840 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
2f850 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
2f860 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
2f870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
2f880 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2f890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
2f8a0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
2f8b0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
2f8c0 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
2f8d0 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54 68  *.** {F16706} Th
2f8e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
2f8f0 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
2f900 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
2f910 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
2f920 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
2f930 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
2f940 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
2f950 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
2f960 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
2f970 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2f980 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2f990 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
2f9a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2f9b0 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
2f9c0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
2f9d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
2f9e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
2f9f0 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
2fa00 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2fa10 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a  needed16()]..**.
2fa20 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ** .*/.int sqlit
2fa30 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2fa40 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
2fa50 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
2fa60 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2fa70 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2fa80 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
2fa90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2faa0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2fab0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2fac0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
2fad0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2fae0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2faf0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2fb00 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2fb10 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2fb20 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2fb30 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2fb40 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2fb50 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2fb60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2fb70 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2fb80 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2fb90 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2fba0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2fbb0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2fbc0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2fbd0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
2fbe0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2fbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2fc00 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2fc10 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2fc20 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2fc30 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2fc40 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
2fc50 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
2fc60 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
2fc70 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
2fc80 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
2fc90 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
2fca0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
2fcb0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
2fcc0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
2fcd0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
2fce0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
2fcf0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
2fd00 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2fd10 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2fd20 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2fd30 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2fd40 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2fd50 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2fd60 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
2fd70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2fd80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2fd90 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2fda0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2fdb0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2fdc0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2fdd0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2fde0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
2fdf0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2fe00 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2fe10 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a  e {F10530}.**.**
2fe20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
2fe30 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ep() function.**
2fe40 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
2fe50 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
2fe60 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
2fe70 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
2fe80 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
2fe90 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
2fea0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
2feb0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
2fec0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2fed0 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
2fee0 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
2fef0 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c  ts with .** mill
2ff00 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
2ff10 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
2ff20 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
2ff30 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a  ounded up to .**
2ff40 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
2ff50 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
2ff60 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
2ff70 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
2ff80 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  y .** requested 
2ff90 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
2ffa0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
2ffb0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  urned..**.** SQL
2ffc0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
2ffd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
2ffe0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
2fff0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
30000 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
30010 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
30020 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ect..**.** INVAR
30030 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
30040 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0533} The [sqlit
30050 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
30060 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74  erface invokes t
30070 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20  he xSleep.**    
30080 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20        method of 
30090 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
300a0 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e  ite3_vfs|VFS] in
300b0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20   order to.**    
300c0 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78        suspend ex
300d0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
300e0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f  urrent thread fo
300f0 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20  r at least.**   
30100 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65         M millise
30110 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  conds..**.** {F1
30120 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  0536} The [sqlit
30130 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
30140 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
30150 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
30160 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65           millise
30170 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
30180 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65  ctually requeste
30190 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69  d of the operati
301a0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ng.**          s
301b0 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67  ystem, which mig
301c0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
301d0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
301e0 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  M..*/.int sqlite
301f0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
30200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
30210 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
30220 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
30230 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33  rary Files {F103
30240 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  10}.**.** If thi
30250 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
30260 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
30270 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
30280 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
30290 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
302a0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
302b0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
302c0 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
302d0 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
302e0 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
302f0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
30300 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
30310 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c  iable.** is NULL
30320 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
30330 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61  QLite does a sea
30340 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
30350 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79  priate temporary
30360 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f  .** file directo
30370 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
30380 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
30390 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
303a0 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65   once a database
303b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68   connection.** h
303c0 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
303d0 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
303e0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
303f0 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
30400 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
30410 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
30420 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
30430 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
30440 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
30450 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
30460 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
30470 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
30480 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
30490 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
304a0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
304b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
304c0 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
304d0 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20  The Database Is 
304e0 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
304f0 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a  ode {F12930}.**.
30500 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
30510 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
30520 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30530 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
30540 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
30550 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
30560 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
30570 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
30580 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
30590 63 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63  ctively.   Autoc
305a0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
305b0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20  .** by default. 
305c0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
305d0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
305e0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
305f0 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ent..** Autocomm
30600 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
30610 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
30620 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
30630 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
30640 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
30650 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
30660 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
30670 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
30680 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
30690 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  s (errors includ
306a0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
306b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
306c0 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  ], .** [SQLITE_N
306d0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
306e0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
306f0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
30700 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
30710 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
30720 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
30730 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
30740 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
30750 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65  nd out if SQLite
30760 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
30770 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
30780 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
30790 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
307a0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
307b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
307c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
307d0 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
307e0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
307f0 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  it(D)] interface
30800 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
30810 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  o or.**         
30820 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61   zero if the [da
30830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30840 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f  n] D is or is no
30850 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  t in autocommit.
30860 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65  **          mode
30870 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
30880 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41  **.** {F12932} A
30890 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
308a0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
308b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20  .**.** {F12933} 
308c0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
308d0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
308e0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47   successful [BEG
308f0 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
30900 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75  *.** {F12934} Au
30910 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
30920 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75   enabled by a su
30930 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54  ccessful [COMMIT
30940 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a  ] or [ROLLBACK].
30950 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74  **          stat
30960 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a  ement..** .**.**
30970 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
30980 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66  *.** {U12936} If
30990 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
309a0 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
309b0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
309c0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
309d0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63            connec
309e0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
309f0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
30a00 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
30a10 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  urn value.**    
30a20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e        is undefin
30a30 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
30a40 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
30a50 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
30a60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46  .** CAPI3REF:  F
30a70 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
30a80 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
30a90 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30aa0 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13120}.**.** T
30ab0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
30ac0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  ndle interface.*
30ad0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73  * returns the [s
30ae0 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
30af0 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63  e handle to whic
30b00 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  h a.** [prepared
30b10 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
30b20 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61  ngs..** The data
30b30 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
30b40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30b50 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  db_handle.** is 
30b60 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30b70 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
30b80 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
30b90 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
30ba0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
30bb0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
30bc0 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
30bd0 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
30be0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
30bf0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
30c00 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
30c10 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
30c20 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
30c30 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
30c40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30c50 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
30c60 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
30c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30c80 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
30c90 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
30ca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30cb0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74  ent] S..*/.sqlit
30cc0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
30cd0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
30ce0 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  mt*);.../*.** CA
30cf0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
30d00 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
30d10 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
30d20 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a  ks {F12950}.**.*
30d30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
30d40 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
30d50 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
30d60 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
30d70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
30d80 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30d90 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
30da0 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
30db0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
30dc0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
30dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
30de0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
30df0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30e00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30e10 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
30e20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
30e30 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
30e40 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
30e50 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
30e60 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
30e70 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30e80 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
30e90 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
30ea0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
30eb0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
30ec0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
30ed0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
30ee0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30f00 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
30f10 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
30f20 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
30f30 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
30f40 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
30f50 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
30f60 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
30f70 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
30f80 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
30f90 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
30fa0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
30fb0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
30fc0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
30fd0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
30fe0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a  registered, its.
30ff0 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ** pArg value is
31000 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
31010 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
31020 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
31030 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
31040 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
31050 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
31060 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
31070 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
31080 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
31090 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
310a0 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
310b0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
310c0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
310d0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
310e0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
310f0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
31100 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
31110 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
31120 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54  k to occur..** T
31130 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
31140 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
31150 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
31160 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
31170 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
31180 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
31190 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
311a0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
311b0 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
311c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
311d0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
311e0 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
311f0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
31200 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
31210 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
31220 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f  n-zero..** <todo
31230 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20  > Check on this 
31240 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68  </todo>.**.** Th
31250 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65  ese are experime
31260 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
31270 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20  and are subject 
31280 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a  to change..**.**
31290 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
312a0 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20  ** {F12951} The 
312b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
312c0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
312d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
312e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
312f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
31300 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
31310 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
31320 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
31330 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
31340 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e  ction commits on
31350 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31360 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
31370 7b 46 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71  {F12952} The [sq
31380 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
31390 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
313a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
313b0 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
313c0 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
313d0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
313e0 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  th the same .** 
313f0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
31400 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20  se connection ] 
31410 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74  D , or NULL on t
31420 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
31430 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
31440 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61  particular [data
31450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31460 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35   D..**.** {F1295
31470 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
31480 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
31490 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
314a0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
314b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
314c0 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
314d0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
314e0 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61  2954} If the F a
314f0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
31500 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
31510 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
31520 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
31530 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
31540 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
31550 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  celled and no ca
31560 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
31570 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
31580 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
31590 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20   commits..**.** 
315a0 7b 46 31 32 39 35 35 7d 20 49 66 20 74 68 65 20  {F12955} If the 
315b0 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
315c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
315d0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
315e0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
315f0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
31600 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
31610 20 7b 46 31 32 39 36 31 7d 20 54 68 65 20 5b 73   {F12961} The [s
31620 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
31630 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
31640 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
31650 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31660 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
31670 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
31680 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
31690 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
316a0 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
316b0 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
316c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
316d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
316e0 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20  ** {F12962} The 
316f0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
31700 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
31710 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31720 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20   the P.**       
31730 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d     argument from
31740 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
31750 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ll with the same
31760 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64   .**          [d
31770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31780 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c  on ] D , or NULL
31790 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
317a0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ll.**          f
317b0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
317c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
317d0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
317e0 46 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c  F12963} Each cal
317f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  l to [sqlite3_ro
31800 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f  llback_hook()] o
31810 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61  verwrites the ca
31820 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
31830 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79     registered by
31840 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a   prior calls..**
31850 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49 66 20  .** {F12964} If 
31860 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74  the F argument t
31870 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  o [sqlite3_rollb
31880 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
31890 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20   is NULL.**     
318a0 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f       then the ro
318b0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
318c0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65  back is cancelle
318d0 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
318e0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
318f0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
31900 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
31910 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  s back..*/.void 
31920 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
31930 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
31940 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
31950 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
31960 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
31970 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
31980 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
31990 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
319a0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
319b0 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
319c0 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 37 30  allbacks {F12970
319d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
319e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
319f0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
31a00 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
31a10 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ack function wit
31a20 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
31a30 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69  onnection identi
31a40 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
31a50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
31a60 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
31a70 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
31a80 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
31a90 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
31aa0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
31ab0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
31ac0 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
31ad0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d  tion for the sam
31ae0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  e .** database c
31af0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
31b00 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rridden..**.** T
31b10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
31b20 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
31b30 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
31b40 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
31b50 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61   .** row is upda
31b60 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
31b70 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68   deleted. .** Th
31b80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31b90 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
31ba0 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66   is.** a copy of
31bb0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
31bc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  ent to sqlite3_u
31bd0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
31be0 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
31bf0 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  back .** argumen
31c00 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
31c10 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
31c20 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20  LITE_DELETE] or 
31c30 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
31c40 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
31c50 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
31c60 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
31c70 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e  allback to be in
31c80 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
31c90 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72  ird and .** four
31ca0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
31cb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
31cc0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
31cd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
31ce0 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65  d .** table name
31cf0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
31d00 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
31d10 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
31d20 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
31d30 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f   .** the rowid o
31d40 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e  f the row..** In
31d50 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
31d60 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
31d70 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
31d80 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74  .** the update t
31d90 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
31da0 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
31db0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
31dc0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
31dd0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
31de0 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
31df0 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
31e00 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
31e10 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ence)..**.** If 
31e20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
31e30 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
31e40 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20  registered, its 
31e50 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73  pArg value.** is
31e60 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
31e70 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
31e80 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  turned..**.** IN
31e90 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
31ea0 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71  {F12971} The [sq
31eb0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
31ec0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
31ed0 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62  ace causes callb
31ee0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
31ef0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
31f00 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69   invoked with fi
31f10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20  rst parameter P 
31f20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
31f30 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77       a table row
31f40 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e   is modified, in
31f50 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74  serted, or delet
31f60 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ed on.**        
31f70 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
31f80 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
31f90 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20 5b 73   {F12973} The [s
31fa0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31fb0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
31fc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
31fd0 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
31fe0 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20     of P for the 
31ff0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e  previous call on
32000 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
32010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32020 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  D,.**          o
32030 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66  r NULL for the f
32040 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  irst call..**.**
32050 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74 68 65   {F12975} If the
32060 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
32070 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69  lback F in [sqli
32080 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
32090 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20  D,F,P)].**      
320a0 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e      is NULL then
320b0 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63   the no update c
320c0 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64  allbacks are mad
320d0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37  e..**.** {F12977
320e0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
320f0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
32100 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72  ook(D,F,P)] over
32110 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c  rides prior call
32120 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
32130 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66   the same interf
32140 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ace on the same 
32150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32160 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
32170 46 31 32 39 37 39 7d 20 54 68 65 20 75 70 64 61  F12979} The upda
32180 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
32190 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
321a0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
321b0 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  stem.**         
321c0 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73 20   tables such as 
321d0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
321e0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
321f0 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a  e are modified..
32200 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54  **.** {F12981} T
32210 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
32220 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61 74  ter to the updat
32230 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20  e callback .**  
32240 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f          is one o
32250 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
32260 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
32270 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  E] or [SQLITE_UP
32280 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DATE],.**       
32290 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20     depending on 
322a0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
322b0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
322c0 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76  llback to be inv
322d0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
322e0 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 61  983} The third a
322f0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
32300 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
32310 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
32320 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
32330 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
32340 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
32350 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65 20  s which are the 
32360 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
32370 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
32380 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74  e and table that
32390 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65   is being update
323a0 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20  d...** {F12985} 
323b0 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
323c0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
323d0 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
323e0 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20   row after.**   
323f0 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e 67         the chang
32400 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69  e occurs..*/.voi
32410 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
32420 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
32430 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
32440 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
32450 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
32460 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
32470 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
32480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32490 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
324a0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
324b0 20 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a   Cache {F10330}.
324c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
324d0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
324e0 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
324f0 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
32500 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
32510 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
32520 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 63  ctures between c
32530 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68  onnections to th
32540 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
32550 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65  .** Sharing is e
32560 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
32570 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61  gument is true a
32580 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
32590 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  he argument.** i
325a0 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43  s false..**.** C
325b0 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
325c0 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
325d0 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65  bled.** for an e
325e0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b  ntire process. {
325f0 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61 20 63  END} This is a c
32600 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
32610 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
32620 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76 65  ..** In prior ve
32630 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
32640 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a  , sharing was.**
32650 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
32660 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
32670 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
32680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
32690 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
326a0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
326b0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
326c0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
326d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
326e0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
326f0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
32700 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
32710 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
32720 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
32730 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
32740 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
32750 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
32760 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
32770 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
32780 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
32790 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
327a0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
327b0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
327c0 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a  .   When shared.
327d0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
327e0 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
327f0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
32800 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
32810 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
32820 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
32830 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
32840 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
32850 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
32860 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
32870 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
32880 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
32890 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
328a0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
328b0 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65  r code].** is re
328c0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
328d0 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63  ..**.** Shared c
328e0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
328f0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
32900 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
32910 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
32920 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
32930 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
32940 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
32950 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
32960 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
32970 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
32980 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ly..**.** INVARI
32990 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  ANTS:.** .** {F1
329a0 30 33 33 31 7d 20 41 20 73 75 63 63 65 73 73 66  0331} A successf
329b0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
329c0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
329d0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29  _shared_cache(B)
329e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
329f0 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  ll enable or dis
32a00 61 62 6c 65 20 73 68 61 72 65 64 20 63 61 63 68  able shared cach
32a10 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73  e mode for any s
32a20 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20  ubsequently.**  
32a30 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64 20          created 
32a40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32a50 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d  tion] in the sam
32a60 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  e process..**.**
32a70 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73   {F10336} When s
32a80 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 65  hared cache is e
32a90 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
32aa0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
32ab0 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
32ac0 20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c    interface will
32ad0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
32ae0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  n error..**.** {
32af0 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c  F10337} The [sql
32b00 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
32b10 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74  ed_cache(B)] int
32b20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
32b30 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
32b40 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
32b50 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
32b60 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73  ed or disabled s
32b70 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a  uccessfully..**.
32b80 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72  ** {F10339} Shar
32b90 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
32ba0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
32bb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32bc0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
32bd0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
32be0 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65   CAPI3REF:  Atte
32bf0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
32c00 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d   Memory {F17340}
32c10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
32c20 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32c30 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
32c40 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65  tempts to.** fre
32c50 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61  e N bytes of hea
32c60 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
32c70 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
32c80 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a  ential memory.**
32c90 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c   allocations hel
32ca0 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
32cb0 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d  e library. {END}
32cc0 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a    Memory used.**
32cd0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
32ce0 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  se pages to impr
32cf0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
32d00 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
32d10 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  .** non-essentia
32d20 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74  l memory.  Sqlit
32d30 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32d40 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  y() returns.** t
32d50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32d60 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
32d70 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  d, which might b
32d80 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a  e more or less.*
32d90 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  * than the amoun
32da0 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a  t requested..**.
32db0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
32dc0 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 68  *.** {F17341} Th
32dd0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  e [sqlite3_relea
32de0 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e  se_memory(N)] in
32df0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
32e00 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
32e10 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20  free N bytes of 
32e20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
32e30 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
32e40 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20  essential.**    
32e50 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c        memory all
32e60 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79  ocations held by
32e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
32e80 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  brary..**.** {F1
32e90 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6342} The [sqlit
32ea0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
32eb0 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68  y(N)] returns th
32ec0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  e number.**     
32ed0 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61 63       of bytes ac
32ee0 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68  tually freed, wh
32ef0 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
32f00 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20  e or less.**    
32f10 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20 61        than the a
32f20 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
32f30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32f40 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
32f50 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32f60 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20  3REF:  Impose A 
32f70 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
32f80 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a  ze {F17350}.**.*
32f90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f  * The sqlite3_so
32fa0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20  ft_heap_limit() 
32fb0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61  interface.** pla
32fc0 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  ces a "soft" lim
32fd0 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
32fe0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
32ff0 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
33000 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69  cated.** by SQLi
33010 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e  te. If an intern
33020 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  al allocation is
33030 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74   requested .** t
33040 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  hat would exceed
33050 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
33060 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72  imit, [sqlite3_r
33070 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
33080 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f   is.** invoked o
33090 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
330a0 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65   to free up some
330b0 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68   space before th
330c0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  e allocation.** 
330d0 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54  is made..**.** T
330e0 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c  he limit is call
330f0 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75  ed "soft", becau
33100 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  se if.** [sqlite
33110 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
33120 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72  ()] cannot.** fr
33130 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
33140 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
33150 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
33160 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
33170 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
33180 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
33190 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
331a0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
331b0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67  eds..**.** A neg
331c0 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
331d0 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
331e0 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
331f0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
33200 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
33210 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
33220 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
33230 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
33240 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ry is exhausted.
33250 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
33260 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
33270 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
33280 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   zero..**.** SQL
33290 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74  ite makes a best
332a0 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72   effort to honor
332b0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
332c0 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69  imit.  .** But i
332d0 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  f the soft heap 
332e0 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20  limit cannot be 
332f0 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69  honored, executi
33300 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69  on will.** conti
33310 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f  nue without erro
33320 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f  r or notificatio
33330 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20  n.  This is why 
33340 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a  the limit is .**
33350 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
33360 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
33370 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
33380 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
33390 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
333a0 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
333b0 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
333c0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
333d0 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
333e0 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
333f0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33400 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
33410 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
33420 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
33430 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
33440 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
33450 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
33460 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
33470 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
33480 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
33490 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
334a0 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
334b0 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
334c0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
334d0 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
334e0 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
334f0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
33500 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
33510 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
33520 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
33530 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
33540 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  reads..**.** INV
33550 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
33560 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16351} The [sql
33570 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
33580 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61  imit(N)] interfa
33590 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74  ce places a soft
335a0 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20   limit.**       
335b0 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e     of N bytes on
335c0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
335d0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
335e0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
335f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69  .**          usi
33600 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
33610 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
33620 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20  3_realloc()] at 
33630 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20  any point.**    
33640 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a        in time..*
33650 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66  *.** {F16352} If
33660 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
33670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
33680 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
33690 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20  c()] would.**   
336a0 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65         cause the
336b0 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66   total amount of
336c0 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72   allocated memor
336d0 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a  y to exceed the.
336e0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74  **          soft
336f0 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65   heap limit, the
33700 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  n [sqlite3_relea
33710 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
33720 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20  invoked.**      
33730 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70      in an attemp
33740 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20  t to reduce the 
33750 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69  memory usage pri
33760 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67  or to proceeding
33770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
33780 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  h the memory all
33790 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e  ocation attempt.
337a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20  .**.** {F16353} 
337b0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
337c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
337d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
337e0 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a  )] that trigger.
337f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65  **          atte
33800 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d  mpts to reduce m
33810 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f  emory usage thro
33820 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61  ugh the soft hea
33830 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  p limit.**      
33840 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f      mechanism co
33850 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74  ntinue even if t
33860 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  he attempt to re
33870 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  duce memory.**  
33880 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73          usage is
33890 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a   unsuccessful..*
338a0 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20  *.** {F16354} A 
338b0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
338c0 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20   value for N in 
338d0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
338e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
338f0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
33900 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  )] means that th
33910 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a  ere is no soft.*
33920 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20  *          heap 
33930 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74  limit and [sqlit
33940 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
33950 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
33960 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
33970 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
33980 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65   is completely e
33990 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  xhausted..**.** 
339a0 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66  {F16355} The def
339b0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
339c0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
339d0 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
339e0 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20  * {F16358} Each 
339f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33a00 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
33a10 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  (N)] overrides t
33a20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
33a30 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c  alues set by all
33a40 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f   prior calls..*/
33a50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f  .void sqlite3_so
33a60 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
33a70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33a80 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65  REF:  Extract Me
33a90 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
33aa0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
33ab0 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12850}.**.** 
33ac0 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  This routine.** 
33ad0 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74  returns meta-dat
33ae0 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
33af0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
33b00 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65  pecific database
33b10 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73  .** table access
33b20 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63  ible using the c
33b30 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
33b40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
33b50 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  irst function .*
33b60 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  * argument..**.*
33b70 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
33b80 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
33b90 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
33ba0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
33bb0 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69  eters to .** thi
33bc0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
33bd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
33be0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
33bf0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
33c00 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
33c10 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
33c20 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
33c30 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
33c40 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
33c50 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
33c60 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
33c70 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
33c80 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
33c90 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
33ca0 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
33cb0 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
33cc0 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  m as the databas
33cd0 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f  e engine uses to
33ce0 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71   .** resolve unq
33cf0 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
33d00 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
33d10 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
33d20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
33d30 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
33d40 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
33d50 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e  and column .** n
33d60 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
33d70 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
33d80 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
33d90 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
33da0 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20  ters .** may be 
33db0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61  NULL..**.** Meta
33dc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
33dd0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
33de0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
33df0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
33e00 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68  ed as.** the 5th
33e10 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
33e20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
33e30 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79  is function. Any
33e40 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72   of these .** ar
33e50 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e  guments may be N
33e60 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
33e70 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
33e80 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
33e90 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61  meta .** informa
33ea0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
33eb0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
33ec0 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75  Parameter     Ou
33ed0 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20 44  tput Type      D
33ee0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d  escription.** --
33ef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33f00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33f10 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20  -.**.**   5th   
33f20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
33f30 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70 65  *      Data type
33f40 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20 20  .**   6th       
33f50 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20    const char*   
33f60 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64     Name of the d
33f70 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
33f80 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20   sequence .**   
33f90 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  7th         int 
33fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
33fb0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
33fc0 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63  has a NOT NULL c
33fd0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38  onstraint.**   8
33fe0 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
33ff0 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
34000 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
34010 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52  s part of the PR
34020 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39  IMARY KEY.**   9
34030 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
34040 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
34050 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
34060 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a  s AUTOINCREMENT.
34070 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a  ** </pre>.**.**.
34080 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  ** The memory po
34090 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
340a0 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
340b0 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
340c0 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74  the .** declarat
340d0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
340e0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
340f0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
34100 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a  til the next .**
34110 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c   call to any sql
34120 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
34130 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
34140 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
34150 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
34160 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72  w, then an error
34170 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
34180 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
34190 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
341a0 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
341b0 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
341c0 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52  n .** INTEGER PR
341d0 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e  IMARY KEY column
341e0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
341f0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
34200 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a  hen the output .
34210 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
34220 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
34230 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
34240 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65  d column. If the
34250 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
34260 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
34270 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  IPK column, then
34280 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72 61   the output para
34290 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
342a0 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  s .** follows:.*
342b0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
342c0 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
342d0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
342e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
342f0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
34300 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
34310 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
34320 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
34330 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
34340 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  </pre>.**.** Thi
34350 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
34360 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
34370 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
34380 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
34390 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
343a0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
343b0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
343c0 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
343d0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
343e0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
343f0 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20  an SQLITE error 
34400 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
34410 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
34420 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e  ssage.** left in
34430 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
34440 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72  ndle (to be retr
34450 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
34460 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a  te3_errmsg())..*
34470 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73  *.** This API is
34480 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
34490 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
344a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
344b0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
344c0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
344d0 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73  ADATA preprocess
344e0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
344f0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
34500 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
34510 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
34520 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
34530 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
34540 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
34550 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
34560 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
34570 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
34580 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
34590 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
345a0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
345b0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
345c0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
345d0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
345e0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
345f0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
34600 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
34610 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
34620 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
34630 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
34640 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
34650 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
34660 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
34670 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
34680 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
34690 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
346a0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
346b0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
346c0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
346d0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
346e0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
346f0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
34700 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
34710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
34720 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
34730 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
34740 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
34750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34760 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
34770 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a  on {F12600}.**.*
34780 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73  * {F12601} The s
34790 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
347a0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
347b0 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f  e.** attempts to
347c0 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20   load an SQLite 
347d0 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
347e0 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
347f0 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65  he file.** zFile
34800 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65  . {F12602} The e
34810 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
34820 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50  roc. {F12603} zP
34830 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20  roc may be 0.** 
34840 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
34850 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
34860 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c  try point defaul
34870 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74 65  ts.** to "sqlite
34880 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
34890 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 34  "..**.** {F12604
348a0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
348b0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
348c0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a 2a  nterface shall.*
348d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
348e0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
348f0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
34900 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
34910 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a  goes wrong..**.*
34920 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49 66  * {F12605}.** If
34930 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
34940 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
34950 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
34960 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  .** sqlite3_load
34970 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
34980 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
34990 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70 7a  empt to fill *pz
349a0 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20  ErrMsg with .** 
349b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
349c0 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
349d0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
349e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
349f0 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20  c()]..** {END}  
34a00 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
34a10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65  tion should free
34a20 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20   this memory.** 
34a30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
34a40 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
34a50 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20 45  ** {F12606}.** E
34a60 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
34a70 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
34a80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
34a90 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
34aa0 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f  nsion()].** prio
34ab0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
34ac0 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f  s API or an erro
34ad0 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
34ae0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
34af0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
34b00 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
34b10 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
34b20 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
34b30 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
34b40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
34b50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
34b60 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
34b70 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
34b80 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
34b90 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
34ba0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
34bb0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
34bc0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
34bd0 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
34be0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
34bf0 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
34c00 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
34c10 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
34c20 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
34c30 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
34c40 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69   Disable Extensi
34c50 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36  on Loading {F126
34c60 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20  20}.**.** So as 
34c70 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
34c80 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
34c90 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
34ca0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
34cb0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
34cc0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
34cd0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
34ce0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
34cf0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
34d00 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
34d10 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
34d20 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
34d30 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49  following.** API
34d40 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
34d50 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
34d60 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
34d70 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
34d80 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46   and.** off.  {F
34d90 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66 66  12622} It is off
34da0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e   by default. {EN
34db0 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  D} See ticket #1
34dc0 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  863..**.** {F126
34dd0 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c  21} Call the sql
34de0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
34df0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
34e00 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f  tine.** with ono
34e10 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78  ff==1 to turn ex
34e20 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
34e30 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69  on.** and call i
34e40 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
34e50 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20  to turn it back 
34e60 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44 7d  off again. {END}
34e70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34e80 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
34e90 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
34ea0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
34eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34ec0 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74  Make Arrangement
34ed0 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c  s To Automatical
34ee0 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  ly Load An Exten
34ef0 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a  sion {F12640}.**
34f00 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69  .** {F12641} Thi
34f10 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  s function.** re
34f20 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
34f30 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
34f40 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74   that is automat
34f50 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a  ically invoked.*
34f60 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  * whenever a new
34f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34f80 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75  tion is opened u
34f90 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
34fa0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
34fb0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
34fc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
34fd0 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  2()]. {END}.**.*
34fe0 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62  * This API can b
34ff0 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f  e invoked at pro
35000 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20  gram startup in 
35010 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65  order to registe
35020 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
35030 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b   statically link
35040 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68  ed extensions th
35050 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c  at will be avail
35060 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e  able.** to all n
35070 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
35080 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ections..**.** {
35090 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74  F12642} Duplicat
350a0 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65  e extensions are
350b0 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c   detected so cal
350c0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
350d0 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  e multiple.** ti
350e0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
350f0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  e extension is h
35100 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  armless..**.** {
35110 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75  F12643} This rou
35120 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
35130 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
35140 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
35150 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62  ay.** that is ob
35160 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
35170 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e  te_malloc(). {EN
35180 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20  D} If you run a 
35190 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63  memory leak.** c
351a0 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70  hecker on your p
351b0 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65  rogram and it re
351c0 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63  ports a leak bec
351d0 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
351e0 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f  array, then invo
351f0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
35200 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
35210 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ()] prior.** to 
35220 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65  shutdown to free
35230 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a   the memory..**.
35240 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f  ** {F12644} Auto
35250 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
35260 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c   apply across al
35270 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d  l threads. {END}
35280 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
35290 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
352a0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
352b0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
352c0 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
352d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
352e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
352f0 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
35300 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78  xtension(void *x
35310 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f  EntryPoint);.../
35320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
35330 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
35340 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
35350 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F12660}.**.** 
35360 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20 66 75  {F12661} This fu
35370 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
35380 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
35390 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75 74  egistered.** aut
353a0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
353b0 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a 2a  s. {END}  This.*
353c0 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
353d0 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61   the effect of a
353e0 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65  ll prior [sqlite
353f0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
35400 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a  ()].** calls..**
35410 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69  .** {F12662} Thi
35420 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20  s call disabled 
35430 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
35440 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65  ions in all thre
35450 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ads. {END}.**.**
35460 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
35470 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
35480 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
35490 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
354a0 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
354b0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
354c0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ite..*/.void sql
354d0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
354e0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
354f0 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  .../*.****** EXP
35500 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
35510 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
35520 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
35530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
35540 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
35550 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
35560 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
35570 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
35580 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
35590 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
355a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
355b0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
355c0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
355d0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
355e0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
355f0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
35600 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
35610 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
35620 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
35630 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
35640 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
35650 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
35660 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
35670 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
35680 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
35690 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
356a0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
356b0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
356c0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
356d0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
356e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
356f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
35700 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
35710 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
35720 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
35730 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
35740 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35750 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35760 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
35770 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
35780 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35790 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
357a0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
357b0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
357c0 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31  Table Object {F1
357d0 38 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  8000}.** KEYWORD
357e0 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
357f0 65 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65  e.**.** A module
35800 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76   is a class of v
35810 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20  irtual tables.  
35820 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64  Each module is d
35830 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20  efined.** by an 
35840 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
35850 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
35860 75 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63  ure.  This struc
35870 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a  ture consists.**
35880 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
35890 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
358a0 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  e..*/.struct sql
358b0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
358c0 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
358d0 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
358e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
358f0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
35900 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
35910 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
35920 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
35930 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
35940 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
35950 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
35960 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
35970 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
35980 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
35990 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
359a0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
359b0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
359c0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
359d0 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
359e0 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
359f0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35a00 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
35a10 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
35a20 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
35a30 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35a40 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35a50 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
35a60 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
35a70 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
35a80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
35a90 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
35aa0 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
35ab0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
35ac0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
35ad0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
35ae0 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
35af0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35b00 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
35b10 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
35b20 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
35b30 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
35b40 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
35b50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
35b60 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
35b70 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
35b80 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
35b90 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
35ba0 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
35bb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
35bc0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
35bd0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
35be0 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
35bf0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
35c00 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
35c10 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
35c20 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
35c30 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
35c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
35c50 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
35c60 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
35c70 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
35c80 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
35c90 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
35ca0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
35cb0 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
35cc0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35cd0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35ce0 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
35cf0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
35d00 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
35d10 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
35d20 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
35d30 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
35d40 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
35d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35d60 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
35d70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35d80 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35d90 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
35da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
35db0 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20  id **ppArg);..  
35dc0 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
35dd0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
35de0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
35df0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
35e00 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
35e10 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
35e20 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46  g Information {F
35e30 31 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18100}.** KEYWOR
35e40 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
35e50 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
35e60 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
35e70 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
35e80 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
35e90 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
35ea0 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
35eb0 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
35ec0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
35ed0 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  om the xBestInde
35ee0 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  x.** method of a
35ef0 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  n sqlite3_module
35f00 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
35f10 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
35f20 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
35f30 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
35f40 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
35f50 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
35f60 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
35f70 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
35f80 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
35f90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
35fa0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
35fb0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
35fc0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
35fd0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a   of the.** form:
35fe0 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63  .**.**         c
35ff0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a  olumn OP expr.**
36000 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20  .** Where OP is 
36010 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
36020 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20  &gt;, or &gt;=. 
36030 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75   .** The particu
36040 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20  lar operator is 
36050 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f  stored.** in aCo
36060 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20  nstraint[].op.  
36070 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
36080 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
36090 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72  d in .** aConstr
360a0 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20  aint[].iColumn. 
360b0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
360c0 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
360d0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
360e0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
360f0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
36100 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
36110 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
36120 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
36130 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
36140 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70  ot..**.** The op
36150 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
36160 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
36170 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
36180 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
36190 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
361a0 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
361b0 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
361c0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
361d0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
361e0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
361f0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
36200 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
36210 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
36220 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  ..** The aConstr
36230 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
36240 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
36250 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20  clause terms in 
36260 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66  the correct.** f
36270 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74  orm that refer t
36280 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
36290 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
362a0 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
362b0 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** Information 
362c0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
362d0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
362e0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
362f0 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20  ]..** Each term 
36300 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
36310 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
36320 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
36330 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  use..**.** The x
36340 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
36350 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
36360 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
36370 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
36380 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
36390 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
363a0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
363b0 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
363c0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
363d0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
363e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
363f0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
36400 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
36410 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
36420 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
36430 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
36440 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
36450 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
36460 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
36470 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
36480 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
36490 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
364a0 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
364b0 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
364c0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
364d0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
364e0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
364f0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
36500 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46  d passed into xF
36510 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65  ilter..** sqlite
36520 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64  3_free() is used
36530 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
36540 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  if needToFreeIdx
36550 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
36560 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f  ** The orderByCo
36570 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
36580 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46  t output from xF
36590 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72  ilter will occur
365a0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
365b0 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
365c0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
365d0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
365e0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
365f0 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
36600 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
36610 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
36620 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
36630 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
36640 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
36650 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
36660 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
36670 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
36680 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
36690 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
366a0 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
366b0 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
366c0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
366d0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
366e0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
366f0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
36700 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
36710 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
36720 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
36730 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
36740 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
36750 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
36760 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
36770 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
36780 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
36790 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
367a0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
367b0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
367c0 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
367d0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
367e0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
367f0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
36800 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
36810 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
36820 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
36830 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
36840 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
36850 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
36860 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
36870 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
36880 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
36890 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
368a0 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
368b0 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
368c0 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
368d0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
368e0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
368f0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
36900 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
36910 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
36920 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
36930 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
36940 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
36950 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
36960 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
36970 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
36980 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
36990 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
369a0 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
369b0 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
369c0 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
369d0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
369e0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
369f0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
36a00 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
36a10 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
36a20 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
36a30 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
36a40 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
36a50 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
36a60 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
36a70 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
36a80 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
36a90 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
36aa0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
36ab0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
36ac0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
36ad0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
36ae0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
36af0 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
36b00 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
36b10 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
36b20 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
36b30 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
36b40 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
36b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36b60 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
36b70 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36b80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
36b90 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
36ba0 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
36bb0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
36bc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
36bd0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
36be0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
36bf0 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
36c00 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
36c10 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
36c20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
36c30 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
36c40 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
36c50 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
36c60 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
36c70 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36c80 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
36c90 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
36ca0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36cb0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
36cc0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36cd0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
36ce0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
36cf0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36d00 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
36d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36d20 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
36d30 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
36d40 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
36d50 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
36d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36d70 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
36d80 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
36d90 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 30 30 7d  ntation {F18200}
36da0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
36db0 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ine is used to r
36dc0 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f  egister a new mo
36dd0 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61  dule name with a
36de0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e  n SQLite.** conn
36df0 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20  ection.  Module 
36e00 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65  names must be re
36e10 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20  gistered before 
36e20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20  creating new.** 
36e30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f  virtual tables o
36e40 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72  n the module, or
36e50 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72   before using pr
36e60 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61  eexisting virtua
36e70 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74  l.** tables of t
36e80 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e  he module..*/.in
36e90 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36ea0 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74  _module(.  sqlit
36eb0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
36ec0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
36ed0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
36ee0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
36ef0 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
36f00 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
36f10 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
36f20 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
36f30 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
36f40 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68  le *,    /* Meth
36f50 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
36f60 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20  le */.  void *  
36f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f80 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
36f90 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
36fa0 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  onnect */.);../*
36fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36fc0 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
36fd0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
36fe0 61 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d 0a 2a  ation {F18210}.*
36ff0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
37000 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  e is identical t
37010 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  o the sqlite3_cr
37020 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65  eate_module() me
37030 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65  thod above,.** e
37040 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
37050 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f  lows a destructo
37060 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  r function to be
37070 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69   specified. It i
37080 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65  s.** even more e
37090 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e  xperimental than
370a0 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65   the rest of the
370b0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
370c0 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  API..*/.int sqli
370d0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
370e0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
370f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37100 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
37110 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
37120 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
37130 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
37140 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
37150 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
37160 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
37170 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
37180 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *,    /* Methods
37190 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
371a0 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
371b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
371c0 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
371d0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
371e0 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
371f0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
37200 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
37210 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
37220 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
37230 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
37240 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
37250 4f 62 6a 65 63 74 20 7b 46 31 38 30 31 30 7d 0a  Object {F18010}.
37260 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
37270 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
37280 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
37290 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
372a0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
372b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
372c0 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
372d0 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
372e0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ar instance of t
372f0 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
37300 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
37310 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
37320 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
37330 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
37340 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37350 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f  .   The.** purpo
37360 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
37370 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
37380 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
37390 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f  s that are commo
373a0 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  n.** to all modu
373b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
373c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
373d0 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
373e0 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
373f0 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
37400 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
37410 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
37420 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
37430 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  () to zErrMsg.  
37440 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
37450 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
37460 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
37470 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
37480 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
37490 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69  e3_free().** pri
374a0 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
374b0 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
374c0 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20  zErrMsg.  After 
374d0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
374e0 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65  e.** is delivere
374f0 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65  d up to the clie
37500 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  nt application, 
37510 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
37520 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
37530 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c  .** freed by sql
37540 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20  ite3_free() and 
37550 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
37560 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64  d will be zeroed
37570 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20  .  Note.** that 
37580 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37590 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72  ) and sqlite3_fr
375a0 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e  ee() are used on
375b0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
375c0 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74  ld.** since virt
375d0 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63  ual tables are c
375e0 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e  ommonly implemen
375f0 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20  ted in loadable 
37600 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68  extensions which
37610 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  .** do not have 
37620 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65  access to sqlite
37630 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71  3MPrintf() or sq
37640 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a  lite3Free()..*/.
37650 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
37660 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
37670 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
37680 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
37690 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
376a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
376b0 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
376c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
376d0 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
376e0 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ally */.  char *
376f0 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
37700 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
37710 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
37720 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37730 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
37740 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37750 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37760 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37770 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37780 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37790 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
377a0 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20  e Cursor Object 
377b0 20 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59   {F18020}.** KEY
377c0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
377d0 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a  tab_cursor.**.**
377e0 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d   Every module im
377f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
37800 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
37810 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
37820 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65  ructure.** to de
37830 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
37840 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
37850 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
37860 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
37870 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
37880 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
37890 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
378a0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
378b0 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68  he.** xOpen meth
378c0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
378d0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
378e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
378f0 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
37900 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
37910 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
37920 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
37930 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
37940 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
37950 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
37960 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
37970 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
37980 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
37990 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
379a0 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
379b0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
379c0 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
379d0 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
379e0 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
379f0 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
37a00 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
37a10 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
37a20 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
37a30 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
37a40 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
37a50 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37a60 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20  EF: Declare The 
37a70 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74  Schema Of A Virt
37a80 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 32 38  ual Table {F1828
37a90 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72  0}.**.** The xCr
37aa0 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63  eate and xConnec
37ab0 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d  t methods of a m
37ac0 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f  odule use the fo
37ad0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74  llowing API.** t
37ae0 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
37af0 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
37b00 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
37b10 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
37b20 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
37b30 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
37b40 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ement..*/.int sq
37b50 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
37b60 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
37b70 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65  st char *zCreate
37b80 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Table);../*.** C
37b90 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
37ba0 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
37bb0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
37bc0 20 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F18300}.**.** 
37bd0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
37be0 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72  an provide alter
37bf0 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74  native implement
37c00 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69  ations of functi
37c10 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ons.** using the
37c20 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d   xFindFunction m
37c30 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62  ethod.  But glob
37c40 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
37c50 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
37c60 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
37c70 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
37c80 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  loaded..**.** Th
37c90 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72  is API makes sur
37ca0 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  e a global versi
37cb0 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e  on of a function
37cc0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
37cd0 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e  ar.** name and n
37ce0 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
37cf0 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20  ers exists.  If 
37d00 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e  no such function
37d10 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72   exists.** befor
37d20 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61  e this API is ca
37d30 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63  lled, a new func
37d40 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e  tion is created.
37d50 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
37d60 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
37d70 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
37d80 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
37d90 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
37da0 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
37db0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
37dc0 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
37dd0 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
37de0 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
37df0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
37e00 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e   placeholder fun
37e10 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
37e20 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
37e30 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  by virtual table
37e40 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  s..**.** This AP
37e50 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73  I should be cons
37e60 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20 74  idered part of t
37e70 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
37e80 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77   interface,.** w
37e90 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d 65  hich is experime
37ea0 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74  ntal and subject
37eb0 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69   to change..*/.i
37ec0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c  nt sqlite3_overl
37ed0 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c  oad_function(sql
37ee0 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
37ef0 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e  r *zFuncName, in
37f00 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t nArg);../*.** 
37f10 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
37f20 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
37f30 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66  le mechanism def
37f40 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b  ined above (back
37f50 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d   up.** to a comm
37f60 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73  ent remarkably s
37f70 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f  imilar to this o
37f80 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ne) is currently
37f90 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
37fa0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
37fb0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
37fc0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
37fd0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
37fe0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
37ff0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
38000 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
38010 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
38020 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
38030 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
38040 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
38050 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
38060 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
38070 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
38080 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
38090 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
380a0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
380b0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a   comment..**.***
380c0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
380d0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
380e0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
380f0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
38100 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  **.*/../*.** CAP
38110 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
38120 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20  To An Open BLOB 
38130 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F17800}.**.** A
38140 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
38150 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
38160 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
38170 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69 6e  B on which.** in
38180 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63 61  cremental I/O ca
38190 6e 20 62 65 20 70 72 65 66 6f 72 6d 65 64 2e 0a  n be preformed..
381a0 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68  ** Objects of th
381b0 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61  is type are crea
381c0 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
381d0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
381e0 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
381f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
38200 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
38210 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
38220 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
38230 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
38240 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
38250 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
38260 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
38270 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
38280 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
38290 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
382a0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
382b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
382c0 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c  ize of the.** bl
382d0 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  ob in bytes..*/.
382e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
382f0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
38300 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
38310 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
38320 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
38330 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37 38  mental I/O {F178
38340 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  10}.**.** This i
38350 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
38360 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20  a handle to the 
38370 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  blob located.** 
38380 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
38390 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
383a0 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
383b0 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
383c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20 74   other words,  t
383d0 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61  he same blob tha
383e0 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63  t would be selec
383f0 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
38400 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
38410 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
38420 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
38430 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a  rowid = iRow;.**
38440 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a   </pre> {END}.**
38450 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73  .** If the flags
38460 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
38470 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62  n-zero, the blob
38480 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a   is opened for .
38490 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69 74  ** read and writ
384a0 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20  e access. If it 
384b0 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  is zero, the blo
384c0 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
384d0 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e  read .** access.
384e0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
384f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
38500 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69  me is not the fi
38510 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74  lename that cont
38520 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  ains.** the data
38530 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20  base but rather 
38540 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  the symbolic nam
38550 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
38560 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 73 73  e that.** is ass
38570 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 20 64  igned when the d
38580 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
38590 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
385a0 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  CH]..** For the 
385b0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
385c0 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  le, the database
385d0 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e   name is "main".
385e0 20 20 46 6f 72 0a 2a 2a 20 54 45 4d 50 20 74 61    For.** TEMP ta
385f0 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61  bles, the databa
38600 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70  se name is "temp
38610 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  "..**.** On succ
38620 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
38630 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
38640 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71   the new .** [sq
38650 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
38660 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  b handle] is wri
38670 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  tten to *ppBlob.
38680 20 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61   .** Otherwise a
38690 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  n error code is 
386a0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a  returned and .**
386b0 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74   any value writt
386c0 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68  en to *ppBlob sh
386d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
386e0 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a   by the caller..
386f0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
38700 20 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61   sets the databa
38710 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20  se-handle error 
38720 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
38730 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
38740 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
38750 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
38760 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
38770 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  * .** INVARIANTS
38780 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d  :.**.** {F17813}
38790 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
387a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
387b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
387c0 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50  en(D,B,T,C,R,F,P
387d0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
387e0 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20 61  nterface opens a
387f0 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d  n [sqlite3_blob]
38800 20 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65   object P on the
38810 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20   blob.**        
38820 20 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66    in column C of
38830 20 74 61 62 6c 65 20 54 20 69 6e 20 64 61 74 61   table T in data
38840 62 61 73 65 20 42 20 6f 6e 20 5b 64 61 74 61 62  base B on [datab
38850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38860 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 34  D..**.** {F17814
38870 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
38880 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
38890 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
388a0 44 2c 2e 2e 2e 29 5d 20 73 74 61 72 74 73 0a 2a  D,...)] starts.*
388b0 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77  *          a new
388c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20   transaction on 
388d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
388e0 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 20  tion] D if that 
388f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
38900 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 61 6c         is not al
38910 72 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e 73  ready in a trans
38920 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  action..**.** {F
38930 31 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c 69  17816} The [sqli
38940 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c  te3_blob_open(D,
38950 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e  B,T,C,R,F,P)] in
38960 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20 74 68  terface opens th
38970 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20  e blob.**       
38980 20 20 20 66 6f 72 20 72 65 61 64 20 61 6e 64 20     for read and 
38990 77 72 69 74 65 20 61 63 63 65 73 73 2