/ Hex Artifact Content
Login

Artifact 7bbf0c2359fd1de3e337a5ed614b17ddac1b18da:


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 37 20 32 30 30 38 2f  in,v 1.317 2008/
05f0: 30 35 2f 32 31 20 31 35 3a 30 31 3a 32 31 20 73  05/21 15:01:21 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 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  be SQLITE_OK if 
2be0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
2bf0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72  SQL statements r
2c00: 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  un successfully 
2c10: 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  and to completio
2c20: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35  n..**.** {F12105
2c30: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
2c40: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
2c50: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
2c60: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 0a  an appropriate .
2c70: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d  **          non-
2c80: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
2c90: 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61  ] if any SQL sta
2ca0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a  tement fails..**
2cb0: 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20  .** {F12107} If 
2cc0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2cd0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2ce0: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
2cf0: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
2d00: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2d10: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20  results and the 
2d20: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
2d30: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a   not NULL, then.
2d40: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2d50: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2d60: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
2d70: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2d80: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
2d90: 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e        invoked on
2da0: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ce for each row 
2db0: 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a  of result..**.**
2dc0: 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68 65   {F12110} If the
2dd0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
2de0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c  s a non-zero val
2df0: 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ue then [sqlite3
2e00: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
2e10: 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74       shall abort
2e20: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e30: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74  nt it is current
2e40: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a  ly evaluating,.*
2e50: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20  *          skip 
2e60: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
2e70: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  QL statements, a
2e80: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
2e90: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
2ea0: 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71  {F12113} The [sq
2eb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
2ec0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73  utine shall pass
2ed0: 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74   its 4th paramet
2ee0: 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20  er through.**   
2ef0: 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73         as the 1s
2f00: 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  t parameter of t
2f10: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2f20: 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65 20  ** {F12116} The 
2f30: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f40: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
2f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2f60: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
2f70: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
2f80: 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
2f90: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 63  columns in the c
2fa0: 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a  urrent row of.**
2fb0: 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
2fc0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39 7d  ..**.** {F12119}
2fd0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2fe0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65  ec()] routine se
2ff0: 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  ts the 3rd param
3000: 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a 20  eter of its .** 
3010: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
3020: 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79  k to be an array
3030: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3040: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20  strings holding 
3050: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
3060: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20  values for each 
3070: 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
3080: 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65 74  rrent result set
3090: 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 20   row as.**      
30a0: 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f      obtained fro
30b0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
30c0: 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
30d0: 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b 73   {F12122} The [s
30e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
30f0: 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65 20  outine sets the 
3100: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  4th parameter of
3110: 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
3120: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
3130: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3140: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3150: 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20  holding the.**  
3160: 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66          names of
3170: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
3180: 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
3190: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
31a0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
31b0: 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65 20  {F12125} If the 
31c0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31d0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
31e0: 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a  ] is NULL then.*
31f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3200: 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76 65  te3_exec()] neve
3210: 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c 6c  r invokes a call
3220: 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72 79  back.  All query
3230: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
3240: 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74 6c  ults are silentl
3250: 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a  y discarded..**.
3260: 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20 61  ** {F12131} If a
3270: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
3280: 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20  hile parsing or 
3290: 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f  evaluating any o
32a0: 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20  f the SQL.**    
32b0: 20 20 20 20 20 20 68 61 6e 64 65 64 20 69 6e 20        handed in 
32c0: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
32d0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
32e0: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64  (D,S,C,A,E)] and
32f0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
3300: 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20  the E parameter 
3310: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3320: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
3330: 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a  )] shall store.*
3340: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45  *          in *E
3350: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
3360: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72  error message wr
3370: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3380: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20  y obtained.**   
3390: 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c         from [sql
33a0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
33b0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20 54  **.** {F12134} T
33c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
33d0: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75  (D,S,C,A,E)] rou
33e0: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74  tine shall set t
33f0: 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  he value of.**  
3400: 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55          *E to NU
3410: 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e  LL if E is not N
3420: 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72  ULL and there ar
3430: 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a  e no errors..**.
3440: 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65 20  ** {F12137} The 
3450: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3460: 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69  S,C,A,E)] functi
3470: 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65  on shall set the
3480: 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
3490: 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 73          and mess
34a0: 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 76  age accessible v
34b0: 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
34c0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
34d0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
34e0: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
34f0: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3500: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38 7d  ..**.** {F12138}
3510: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
3520: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3530: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3540: 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20 65 6d   is a null or em
3550: 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pty.**          
3560: 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69  string or contai
3570: 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72  ns nothing other
3580: 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65   than whitespace
3590: 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e 64 2f  , comments, and/
35a0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
35b0: 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20  emicolons, then 
35c0: 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69  results of [sqli
35d0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  te3_errcode()],.
35e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35f0: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
3600: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
3610: 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
3620: 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74       shall reset
3630: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20   to indicate no 
3640: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49  errors..**.** LI
3650: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
3660: 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66 69   {U12141} The fi
3670: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
3680: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3690: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c  ] must be an val
36a0: 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20  id and open.**  
36b0: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
36c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
36d0: 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54 68  *.** {U12142} Th
36e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36f0: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62  ction must not b
3700: 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a  e closed while.*
3710: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3730: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20 7b  unning..** .** {
3740: 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c  U12143} The call
3750: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
3760: 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33  uld use [sqlite3
3770: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65  _free()] to free
3780: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
3790: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72   memory that *er
37a0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69  rmsg is left poi
37b0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68  nting at once th
37c0: 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
37d0: 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e      message is n
37e0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
37f0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20  .**.** {U12145} 
3800: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
3810: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
3820: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
3830: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3840: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  **          must
3850: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
3860: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
3870: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3880: 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
3890: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
38a0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
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 2f 2a 20 41 6e 20 6f 70 65         /* An ope
38d0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
38e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
38f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3900: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
3910: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64  L to be evaluted
3920: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
3930: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
3940: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
3950: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
3960: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
3970: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
39a0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
39b0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
39c0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
39f0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
3a00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3a10: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  F: Result Codes 
3a20: 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57  {F10210}.** KEYW
3a30: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3a40: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3a50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ror codes}.**.**
3a60: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
3a70: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
3a80: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
3a90: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
3aa0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
3ab0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
3ac0: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
3ad0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
3ae0: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
3af0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
3b00: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3b10: 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  odes].*/.#define
3b20: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
3b30: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
3b40: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
3b50: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
3b60: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
3b80: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
3b90: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
3ba0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
3bb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3bc0: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
3bd0: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
3be0: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
3bf0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
3c00: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
3c10: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
3c20: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
3c30: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
3c40: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
3c50: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
3c60: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
3c70: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
3c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3c90: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
3ca0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3cb0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
3cc0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3cd0: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
3ce0: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
3cf0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
3d00: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3d10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
3d20: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
3d30: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
3d40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3d50: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
3d60: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
3d70: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
3d80: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
3d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3da0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
3db0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
3dc0: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
3dd0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
3de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3df0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
3e00: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
3e10: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
3e20: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
3e30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
3e40: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
3e50: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
3e60: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
3e70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3e80: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
3e90: 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   12   /* NOT USE
3ea0: 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  D. Table or reco
3eb0: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
3ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
3ed0: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
3ee0: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
3ef0: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
3f00: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
3f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
3f20: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
3f30: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
3f40: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
3f50: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
3f60: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
3f70: 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53    15   /* NOT US
3f80: 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63  ED. Database loc
3f90: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
3fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fb0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
3fc0: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
3fd0: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
3fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
3ff0: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4000: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4010: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4030: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4040: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
4050: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
4060: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
4070: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
4080: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
4090: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
40a0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
40b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
40c0: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
40d0: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
40e0: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
40f0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4100: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4110: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4120: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4130: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4140: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
4150: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
4160: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
4170: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4180: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
4190: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
41a0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
41b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
41c0: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
41d0: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
41e0: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
41f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4200: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4210: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4220: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4230: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4240: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4250: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
4260: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
4270: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
4280: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
4290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42a0: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
42b0: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
42c0: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
42d0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
42e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
42f0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4300: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4310: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4320: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4330: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4340: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4350: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4360: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32  ult Codes {F1022
4370: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
4380: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4390: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
43a0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
43b0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
43c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
43d0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
43e0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
43f0: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4400: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4410: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4420: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4430: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4440: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4450: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4460: 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66   that.** many of
4470: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4480: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72  des are too cour
4490: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
44a0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
44b0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
44c0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
44d0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
44e0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
44f0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4500: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4510: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4520: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4530: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4540: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4550: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4560: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4570: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4580: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4590: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
45a0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
45b0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
45c0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
45d0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
45e0: 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61 74 61  ** for each data
45f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4600: 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
4610: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4620: 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41  lt_codes()].** A
4630: 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20  PI..** .** Some 
4640: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4650: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4660: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
4670: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
4680: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
4690: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
46a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
46b0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
46c0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
46d0: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
46e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
46f0: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4700: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4710: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4720: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4730: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4740: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4750: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
4760: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
4770: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
4780: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
4790: 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 49  y zero..** .** I
47a0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
47b0: 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20 73 79   {F10223} The sy
47c0: 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20  mbolic name for 
47d0: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  an extended resu
47e0: 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63  lt code always c
47f0: 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
4800: 20 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72      a related pr
4810: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4820: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a  e as a prefix..*
4830: 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 72  *.** {F10224} Pr
4840: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4850: 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20  e names contain 
4860: 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61  a single "_" cha
4870: 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  racter..**.** {F
4880: 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20  10225} Extended 
4890: 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65  result code name
48a0: 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  s contain two or
48b0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
48c0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ters..**.** {F10
48d0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
48e0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
48f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4900: 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  e contains the.*
4910: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72  *          numer
4920: 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20  ic value of its 
4930: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
4940: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4950: 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e in.**         
4960: 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69   its least signi
4970: 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a  ficant 8 bits..*
4980: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4990: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
49a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
49b0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
49c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
49d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
49e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
49f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
4a00: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
4a10: 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  TE         (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4a30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4a40: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4a50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4a60: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4a80: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4a90: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4aa0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
4ab0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
4ac0: 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c  UNCATE      (SQL
4ad0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
4ae0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4af0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
4b00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b10: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4b30: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4b40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b50: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4b60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4b70: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51  DLOCK        (SQ
4b80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
4b90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4ba0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
4bb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4bc0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
4bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c00: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4c30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c40: 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20  (12<<8))../*.** 
4c50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
4c60: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
4c70: 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30  erations {F10230
4c80: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  }.**.** These bi
4c90: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
4ca0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
4cb0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
4cc0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
4cd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
4ce0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
4cf0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
4d00: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f  ameter to the xO
4d10: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
4d20: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
4d30: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4d50: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
4d60: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
4d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4d80: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
4d90: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
4da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4db0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
4dc0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4de0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
4df0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
4e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4e10: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
4e20: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
4e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4e40: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
4e50: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
4e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4e70: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
4e80: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4ea0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
4eb0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
4ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4ed0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
4ee0: 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64     0x00000800.#d
4ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4f00: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
4f10: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
4f20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4f30: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
4f40: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64     0x00002000.#d
4f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
4f60: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
4f70: 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f     0x00004000../
4f80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
4f90: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
4fa0: 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a  stics {F10240}.*
4fb0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4fc0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4fd0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4fe0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4ff0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5000: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5010: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5020: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5030: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5040: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5050: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5060: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5070: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5080: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5090: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
50a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
50b0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
50c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
50d0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
50e0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
50f0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5100: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5110: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5120: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5130: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5140: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5150: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5160: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5170: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5180: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5190: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
51a0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
51b0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
51c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
51d0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
51e0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
51f0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5200: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5210: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5220: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5230: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5240: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5250: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5260: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5270: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5280: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5290: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
52a0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
52b0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
52c0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
52d0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
52e0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
52f0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5300: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5310: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5320: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5330: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5340: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5350: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5370: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5380: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
53a0: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
53b0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
53c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
53d0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
53e0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
53f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5400: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5410: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5420: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5430: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5440: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5460: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5470: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5480: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5490: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
54a0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
54b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
54c0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
54d0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
54e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
54f0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5500: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5510: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5520: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30  king Levels {F10
5530: 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  250}.**.** SQLit
5540: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
5550: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
5560: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
5570: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
5580: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
5590: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
55a0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
55b0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
55c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
55d0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
55f0: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
5620: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
5630: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
5640: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
5650: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
5660: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5680: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
5690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
56a0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
56b0: 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31  n Type Flags {F1
56c0: 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  0260}.**.** When
56d0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
56e0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
56f0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
5700: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5710: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
5720: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
5730: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
5740: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
5750: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
5760: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
5770: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
5780: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
5790: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
57a0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
57b0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
57c0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
57d0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
57e0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
57f0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
5800: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20  be flushed. The 
5810: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5820: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a  AL flag means .*
5830: 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  * to use normal 
5840: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5850: 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  s. The SQLITE_SY
5860: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61  NC_FULL flag mea
5870: 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ns .** to use Ma
5880: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
5890: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
58a0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
58b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
58c0: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
58d0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
58e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
58f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
5900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5910: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
5920: 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a     0x00010.../*.
5930: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5940: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
5950: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31  ile Handle {F111
5960: 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10}.**.** An [sq
5970: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5980: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
5990: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
59a0: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
59b0: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
59c0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
59d0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
59e0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
59f0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
5a00: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
5a10: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
5a20: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
5a30: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
5a40: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
5a50: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
5a60: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
5a70: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5a80: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
5a90: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
5aa0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
5ab0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
5ac0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
5ad0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
5ae0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
5af0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
5b00: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
5b10: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
5b20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
5b30: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
5b40: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
5b50: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
5b60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
5b70: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
5b80: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
5b90: 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a  Object {F11120}.
5ba0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
5bb0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
5bc0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
5bd0: 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69  en method contai
5be0: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  ns a pointer to.
5bf0: 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
5c00: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20  f this object.  
5c10: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
5c20: 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f  nes the.** metho
5c30: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
5c40: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
5c50: 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 68  tions against th
5c60: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a  e open file..**.
5c70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
5c80: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
5c90: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
5ca0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5cb0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
5cc0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
5cd0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
5ce0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
5cf0: 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63 6f  c()..*  The seco
5d00: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e 0a  nd choice is an.
5d10: 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75  ** OS-X style fu
5d20: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51 4c  llsync.  The SQL
5d30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c  ITE_SYNC_DATA fl
5d40: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
5d50: 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74 65  n to.** indicate
5d60: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
5d70: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ata of the file 
5d80: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
5d90: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a 2a  e needs to be.**
5da0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20   synced..** .** 
5db0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
5dc0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
5dd0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
5de0: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
5df0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5e00: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
5e10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5e20: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
5e30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
5e40: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
5e50: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
5e60: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
5e70: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5e80: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
5e90: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
5ea0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
5eb0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
5ec0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
5ed0: 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  .  .** The xChec
5ee0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
5ef0: 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20  method looks.** 
5f00: 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64 61  to see if any da
5f10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5f20: 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  n, either in thi
5f30: 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20  s.** process or 
5f40: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
5f50: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
5f60: 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a  g an RESERVED,.*
5f70: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
5f80: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
5f90: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
5fa0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
5fb0: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
5fc0: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66  sts and false if
5fd0: 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65   not..** .** The
5fe0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
5ff0: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6000: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6010: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6020: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6030: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6040: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6050: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6060: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6070: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6080: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6090: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
60a0: 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ent.** is an int
60b0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20 54  eger opcode.   T
60c0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
60d0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
60e0: 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  c pointer which 
60f0: 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
6100: 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  e a pointer.** t
6110: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6120: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6130: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6140: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6150: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6160: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6170: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6180: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6190: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
61a0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
61b0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
61c0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
61d0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
61e0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
61f0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6200: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6210: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6220: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6230: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6240: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6250: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6260: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f 70  core reserves op
6270: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6280: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6290: 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c 49  use. .** A [SQLI
62a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
62b0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
62c0: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
62d0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
62e0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
62f0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
6300: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
6310: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
6320: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a 2a  d use opcodes .*
6330: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
6340: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
6350: 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  licts..**.** The
6360: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
6370: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
6380: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
6390: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
63a0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
63b0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
63c0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
63d0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
63e0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
63f0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
6400: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
6410: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
6420: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
6430: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6440: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
6450: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
6460: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
6470: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
6480: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
6490: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
64a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
64b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
64c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
64d0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
64e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
64f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
6500: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6510: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
6520: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6530: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
6540: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6550: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
6560: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6570: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
6580: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6590: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
65a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
65c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
65d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
65e0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
65f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6600: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
6610: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6630: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6640: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6650: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6660: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6670: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6680: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6690: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66a0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66b0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
66c0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
66d0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
66e0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
66f0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6700: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6710: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6720: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6730: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6740: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6750: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6760: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6770: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6780: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6790: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67a0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67b0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
67c0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
67d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67e0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
67f0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6800: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6810: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6820: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6830: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6840: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
6850: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6860: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6870: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
6880: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
6890: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
68a0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
68b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
68c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
68d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
68e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
68f0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
6900: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
6910: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
6920: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
6930: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
6940: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6950: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
6960: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
6970: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
6980: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
6990: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
69a0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
69b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
69c0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
69d0: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
69e0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
69f0: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
6a00: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
6a10: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
6a20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
6a30: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6a40: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
6a50: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
6a60: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
6a70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6a80: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6a90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6aa0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6ab0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6ac0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6ad0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6ae0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6af0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6b00: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6b10: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6b20: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6b30: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6b40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6b50: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6b60: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6b70: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
6b80: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
6b90: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
6ba0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
6bb0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6bc0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6bd0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6be0: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
6bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6c00: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6c10: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6c20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6c30: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6c40: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6c50: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6c60: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6c70: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6c80: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
6c90: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
6ca0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
6cb0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6cc0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6cd0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6ce0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6cf0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6d00: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6d10: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6d20: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6d30: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6d40: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6d50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6d60: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6d70: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6d80: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6d90: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6da0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6db0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6dc0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6de0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6df0: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6e00: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6e10: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6e20: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6e30: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6e40: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6e50: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6e60: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6e70: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6e80: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6e90: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6ea0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6eb0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6ec0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6ed0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6ee0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6ef0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6f00: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6f10: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6f20: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6f30: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
6f40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
6f50: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
6f60: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6f70: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
6f80: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
6f90: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6fa0: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
6fb0: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
6fc0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6fd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6fe0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
6ff0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
7000: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
7010: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
7020: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
7030: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7040: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7050: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7060: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7070: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7080: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7090: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
70a0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
70b0: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
70c0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
70d0: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
70e0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
70f0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
7100: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
7110: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
7120: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
7130: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7140: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7150: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7160: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7170: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7180: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7190: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
71a0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
71b0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
71c0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
71d0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
71e0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
71f0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7200: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7210: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7220: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7230: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7240: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7250: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7260: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7270: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7280: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7290: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
72a0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
72b0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
72c0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
72d0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
72e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
72f0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7300: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7310: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
7320: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
7330: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7340: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7350: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7360: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7370: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7380: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7390: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
73a0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
73b0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
73c0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
73d0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
73e0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
73f0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
7400: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
7410: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
7420: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
7430: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7440: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7450: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7460: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7470: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7480: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
7490: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
74a0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
74b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
74c0: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
74d0: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
74e0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
74f0: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
7500: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
7510: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
7520: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
7530: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7540: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7550: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7560: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7570: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7580: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
7590: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
75a0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
75b0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
75c0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
75d0: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
75e0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
75f0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
7600: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
7610: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
7620: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7630: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7640: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7650: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7660: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7670: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7680: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
7690: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
76a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
76b0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
76c0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
76d0: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
76e0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
76f0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
7700: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
7710: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
7720: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
7730: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7740: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7750: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7760: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7770: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7780: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
7790: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
77a0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
77b0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
77c0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
77d0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
77e0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
77f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7800: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
7810: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7820: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
7830: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7840: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7850: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7860: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7870: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
7890: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
78a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
78b0: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
78c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
78d0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
78e0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
78f0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
7900: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
7910: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
7920: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
7930: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7940: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7950: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7960: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7970: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7980: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
7990: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
79a0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
79b0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
79c0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
79d0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
79e0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
79f0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7a00: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7a10: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7a20: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7a30: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7a40: 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  rn .** SQLITE_IO
7a50: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7a60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7a70: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7a80: 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
7a90: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7aa0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7ab0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7ac0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7ad0: 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  dom .** order an
7ae0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7af0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7b00: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7b10: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7b20: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7b30: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7b40: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7b50: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
7b60: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7b70: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7b80: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
7b90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
7ba0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
7bb0: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
7bc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7bd0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7be0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7bf0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7c00: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7c10: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7c20: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7c30: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7c40: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7c50: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
7c60: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
7c70: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
7c80: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
7c90: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
7ca0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7cb0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7cc0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7cd0: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7ce0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7cf0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7d00: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7d10: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7d20: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7d30: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7d40: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7d50: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7d60: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
7d70: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
7d80: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c  QLite .** to hol
7d90: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7da0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7db0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7dc0: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
7dd0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44   to xOpen.  {END
7de0: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
7df0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
7e00: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
7e10: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
7e20: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
7e30: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a  ill it in..** .*
7e40: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66  * {F11149} The f
7e50: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7e60: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7e70: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7e80: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20  _EXISTS] .** to 
7e90: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
7ea0: 73 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stance of a file
7eb0: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
7ec0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
7ed0: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  ] to test to see
7ee0: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73  .** if a file is
7ef0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
7f00: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
7f10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
7f20: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
7f30: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61  e if a file is a
7f40: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
7f50: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c  .  {END} The fil
7f60: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64  e can be a .** d
7f70: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a  irectory..** .**
7f80: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {F11150} SQLite
7f90: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
7fa0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
7fb0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
7fc0: 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  s for.** the out
7fd0: 70 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20  put buffers for 
7fe0: 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64  xGetTempname and
7ff0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8000: 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65 78 61  {F11151} The exa
8010: 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  ct.** size of th
8020: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
8030: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
8040: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
8050: 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64   both .** method
8060: 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 20  s. {END} If the 
8070: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73  output buffer is
8080: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
8090: 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  h, SQLITE_CANTOP
80a0: 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  EN.** should be 
80b0: 72 65 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69  returned. As thi
80c0: 73 20 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20  s is handled as 
80d0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
80e0: 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20   SQLite,.** vfs 
80f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
8100: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 20  should endeavor 
8110: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
8120: 62 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d  by setting .** m
8130: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
8140: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
8150: 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20  e value..** .** 
8160: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
8170: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
8180: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
8190: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
81a0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
81b0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
81c0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
81d0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
81e0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
81f0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
8200: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
8210: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
8220: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
8230: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
8240: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
8250: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
8260: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
8270: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
8280: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
8290: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
82a0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
82b0: 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a   obtained.  The.
82c0: 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  ** xSleep() meth
82d0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
82e0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
82f0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
8300: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
8310: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
8320: 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75   given.  The xCu
8330: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
8340: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8350: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
8360: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
8370: 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69  t date and.** ti
8380: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  me..*/.typedef s
8390: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
83a0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
83b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
83c0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
83d0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
83e0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
83f0: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
8400: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
8410: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
8420: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
8430: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
8440: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
8450: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
8460: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
8470: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
8480: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
8490: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
84a0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
84b0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
84c0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
84d0: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
84e0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
84f0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
8500: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
8510: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
8520: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
8530: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
8540: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
8550: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8560: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
8570: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
8580: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
8590: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
85a0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
85b0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
85c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
85d0: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
85e0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
85f0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
8600: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8610: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29  Name, int flags)
8620: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65  ;.  int (*xGetTe
8630: 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  mpname)(sqlite3_
8640: 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  vfs*, int nOut, 
8650: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
8660: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
8670: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8680: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8690: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
86a0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
86b0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
86c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
86d0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
86e0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
86f0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
8700: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
8710: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
8720: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
8730: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
8740: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
8750: 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76  r *zSymbol);.  v
8760: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8770: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8780: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8790: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
87a0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
87b0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
87c0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
87d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
87e0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
87f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
8800: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
8810: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
8820: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
8830: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
8840: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
8850: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
8860: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
8870: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
8880: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
8890: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
88a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
88b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
88c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 31  VFS method {F111
88d0: 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39  90}.**.** {F1119
88e0: 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  1} These integer
88f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
8900: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
8910: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
8920: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
8930: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
8940: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
8950: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
8960: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
8970: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
8980: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
8990: 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f   method is.** lo
89a0: 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31  oking for.  {F11
89b0: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
89c0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
89d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
89e0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
89f0: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68  cks to see if th
8a00: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 7b  e file exists. {
8a10: 46 31 31 31 39 33 7d 20 57 69 74 68 0a 2a 2a 20  F11193} With.** 
8a20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8a30: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
8a40: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63  cess method chec
8a50: 6b 73 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20  ks to see.** if 
8a60: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
8a70: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8a80: 69 74 61 62 6c 65 2e 20 20 7b 46 31 31 31 39 34  itable.  {F11194
8a90: 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45  } With.** SQLITE
8aa0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 65  _ACCESS_READ the
8ab0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8ac0: 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65  ** checks to see
8ad0: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
8ae0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
8af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8b00: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
8b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
8b20: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
8b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8b40: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
8b50: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
8b60: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
8b70: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
8b80: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32  esult Codes {F12
8b90: 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200}.**.** The s
8ba0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
8bb0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
8bc0: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
8bd0: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
8be0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  * [SQLITE_IOERR_
8bf0: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
8c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
8c10: 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
8c20: 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64 65 64  .** The extended
8c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
8c40: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
8c50: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
8c60: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
8c70: 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ility..**.** INV
8c80: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
8c90: 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  F12201} Each new
8ca0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
8cb0: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
8cc0: 65 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  e the .**       
8cd0: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
8ce0: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
8cf0: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  re.**          d
8d00: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
8d10: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30  lt..**.** {F1220
8d20: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
8d30: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
8d40: 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65  codes(D,F)] inte
8d50: 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62  rface shall enab
8d60: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
8d70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8d80: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a  codes] for the .
8d90: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
8da0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8db0: 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61 72  ] D if the F par
8dc0: 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
8dd0: 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64     is true, or d
8de0: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
8df0: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8e00: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8e10: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8e20: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8e30: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8e40: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8e50: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8e60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8e70: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8e80: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8e90: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8ea0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8eb0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8ec0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8ed0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8ee0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8ef0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8f00: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8f10: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8f20: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8f30: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8f40: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8f50: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8f60: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8f70: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8f80: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8f90: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8fa0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8fb0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
8fc0: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
8fd0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
8fe0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
8ff0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
9000: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
9010: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
9020: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
9030: 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  e from the datab
9040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
9050: 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66  * shown in the f
9060: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
9070: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
9080: 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65   inserts.** have
9090: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
90a0: 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  n this database 
90b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
90c0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
90d0: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
90e0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
90f0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
9100: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a  he rowid of the.
9110: 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ** inserted row 
9120: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
9130: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
9140: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
9150: 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  er.** is running
9160: 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  .  But once the 
9170: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
9180: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
9190: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  turned.** by thi
91a0: 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
91b0: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
91c0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
91d0: 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67  ore the.** trigg
91e0: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
91f0: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
9200: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
9210: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
9220: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
9230: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
9240: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
9250: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
9260: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
9270: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
9280: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
9290: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
92a0: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
92b0: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
92c0: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
92d0: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
92e0: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
92f0: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
9300: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
9310: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
9320: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
9330: 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e  R REPLACE .** en
9340: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
9350: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
9360: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
9370: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
9380: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
9390: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
93a0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
93b0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
93c0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
93d0: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
93e0: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
93f0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
9400: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
9410: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
9420: 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  e. .**.** For th
9430: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
9440: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69  is routine, an i
9450: 6e 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65  nsert is conside
9460: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
9470: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
9480: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
9490: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
94a0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
94b0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d  :.**.** {F12221}
94c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
94d0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
94e0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
94f0: 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
9500: 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65      rowid of the
9510: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
9520: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64  cessful insert d
9530: 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  one.**          
9540: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
9550: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9560: 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
9570: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
9580: 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 20  or higher level 
9590: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
95a0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
95b0: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  e have.**       
95c0: 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69     been no quali
95d0: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a  fying inserts..*
95e0: 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20 54 68  *.** {F12223} Th
95f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
9600: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
9610: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
9620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d  .**          sam
9630: 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c  e value when cal
9640: 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
9650: 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  e trigger contex
9660: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d  t.**          im
9670: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
9680: 20 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c   and after a ROL
9690: 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  LBACK..**.** LIM
96a0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
96b0: 7b 55 31 32 32 33 32 7d 20 49 66 20 61 20 73 65  {U12232} If a se
96c0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 64 6f  parate thread do
96d0: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20  es a new insert 
96e0: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
96f0: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
9700: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
9710: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
9720: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
9730: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
9740: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
9750: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
9760: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
9770: 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20  sert rowid,.**  
9780: 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
9790: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
97a0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
97b0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
97c0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
97d0: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
97e0: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
97f0: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
9800: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20   or the new.**  
9810: 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73          last ins
9820: 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71  ert rowid..*/.sq
9830: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
9840: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
9850: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
9860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9870: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
9880: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
9890: 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a  ied {F12240}.**.
98a0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
98b0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
98c0: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
98d0: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
98e0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
98f0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
9900: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
9910: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
9920: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
9930: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
9940: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
9950: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
9960: 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68  ter.  Only.** ch
9970: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
9980: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
9990: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
99a0: 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44   UPDATE, or.** D
99b0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
99c0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
99d0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
99e0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
99f0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
9a00: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
9a10: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
9a20: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
9a30: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
9a40: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
9a50: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
9a60: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
9a70: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
9a80: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
9a90: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
9aa0: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
9ab0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
9ac0: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
9ad0: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
9ae0: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
9af0: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
9b00: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
9b10: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
9b20: 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
9b30: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
9b40: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
9b50: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
9b60: 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
9b70: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
9b80: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
9b90: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
9ba0: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
9bb0: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
9bc0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
9bd0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
9be0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
9bf0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
9c00: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
9c10: 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
9c20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
9c30: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
9c40: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
9c50: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
9c60: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
9c70: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
9c80: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
9c90: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
9ca0: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
9cb0: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
9cc0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
9cd0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
9ce0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
9cf0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
9d00: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
9d10: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
9d20: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
9d30: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
9d40: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
9d50: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
9d60: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
9d70: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
9d80: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
9d90: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
9da0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
9db0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
9dc0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
9dd0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
9de0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
9df0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
9e00: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
9e10: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
9e20: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
9e30: 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e 20 63 61  **.** So when ca
9e40: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
9e50: 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
9e60: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
9e70: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
9e80: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
9e90: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
9ea0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
9eb0: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
9ec0: 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
9ed0: 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a 20  e top level..** 
9ee0: 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
9ef0: 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  of a trigger, th
9f00: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
9f10: 73 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  s() interface.**
9f20: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
9f30: 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
9f40: 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
9f50: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
9f60: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
9f70: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
9f80: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
9f90: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
9fa0: 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
9fb0: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
9fc0: 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
9fd0: 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
9fe0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69 6e 20 63  not include in c
9ff0: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
a000: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
a010: 73 69 6e 63 65 20 74 68 65 79 20 68 61 76 65 20  since they have 
a020: 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
a030: 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
a040: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63  implements the c
a050: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46  ommand "DELETE F
a060: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f  ROM table" witho
a070: 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c  ut.** a WHERE cl
a080: 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67  ause by dropping
a090: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20   and recreating 
a0a0: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69  the table.  (Thi
a0b0: 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73  s is much.** fas
a0c0: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 20 74  ter than going t
a0d0: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74  hrough and delet
a0e0: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65  ing individual e
a0f0: 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65  lements from the
a100: 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42 65 63  .** table.)  Bec
a110: 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f 70 74  ause of this opt
a120: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64  imization, the d
a130: 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 22  eletions in.** "
a140: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
a150: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
a160: 68 61 6e 67 65 73 20 61 6e 64 20 77 69 6c 6c 20  hanges and will 
a170: 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 0a 2a  not be counted.*
a180: 2a 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  * by the sqlite3
a190: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
a1a0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
a1b0: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
a1c0: 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20 61 6e 20  s..** To get an 
a1d0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
a1e0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
a1f0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
a200: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
a210: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
a220: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
a230: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
a240: 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65 20 5b  * {F12241} The [
a250: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
a260: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
a270: 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d  l return the num
a280: 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
a290: 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63     row changes c
a2a0: 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73  aused by the mos
a2b0: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
a2c0: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20   UPDATE,.**     
a2d0: 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73       or DELETE s
a2e0: 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
a2f0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
a300: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  nnection and.** 
a310: 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e 20           within 
a320: 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
a330: 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  er trigger conte
a340: 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
a350: 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20  here have.**    
a360: 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61        not been a
a370: 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f  ny qualifying ro
a380: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
a390: 20 7b 46 31 32 32 34 33 7d 20 53 74 61 74 65 6d   {F12243} Statem
a3a0: 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ents of the form
a3b0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
a3c0: 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f  blename" with no
a3d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45  .**          WHE
a3e0: 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20  RE clause shall 
a3f0: 63 61 75 73 65 20 73 75 62 73 65 71 75 65 6e 74  cause subsequent
a400: 20 63 61 6c 6c 73 20 74 6f 20 0a 2a 2a 20 20 20   calls to .**   
a410: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
a420: 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72 65  changes()] to re
a430: 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72  turn zero, regar
a440: 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  dless of the.** 
a450: 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
a460: 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c  of rows original
a470: 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ly in the table.
a480: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
a490: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35  NS:.**.** {U1225
a4a0: 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
a4b0: 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
a4c0: 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
a4d0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
a4e0: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
a4f0: 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33    while [sqlite3
a500: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
a510: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
a520: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
a530: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
a540: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
a550: 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  unmeaningful..*/
a560: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
a570: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
a580: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a590: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
a5a0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
a5b0: 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54  F12260}.***.** T
a5c0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
a5d0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
a5e0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
a5f0: 61 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45  aused.** by INSE
a600: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
a610: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
a620: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
a630: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
a640: 20 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f   opened.  The co
a650: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
a660: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
a670: 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e  l trigger.** con
a680: 74 65 78 74 73 2e 20 20 42 75 74 20 74 68 65 20  texts.  But the 
a690: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
a6a0: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
a6b0: 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d  sed to.** implem
a6c0: 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73  ent REPLACE cons
a6d0: 74 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c  traints, do roll
a6e0: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
a6f0: 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72  rocessing,.** or
a700: 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63   DROP table proc
a710: 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63  essing..** The c
a720: 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f  hanges.** are co
a730: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
a740: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
a750: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
a760: 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20  s completed .** 
a770: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
a780: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
a790: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
a7a0: 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a  _reset()] or .**
a7b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
a7c0: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
a7d0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
a7e0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
a7f0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
a800: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45  without.** a WHE
a810: 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f  RE clause by dro
a820: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
a830: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
a840: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a   (This is much.*
a850: 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  * faster than go
a860: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
a870: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
a880: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
a890: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
a8a0: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
a8b0: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
a8c0: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
a8d0: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
a8e0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
a8f0: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
a900: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
a910: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
a920: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
a930: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
a940: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
a950: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
a960: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
a970: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
a980: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
a990: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
a9a0: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
a9b0: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
a9c0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
a9d0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
a9e0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
a9f0: 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54  * .** {F12261} T
aa00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
aa10: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
aa20: 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
aa30: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
aa40: 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
aa50: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
aa60: 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
aa70: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
aa80: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
aa90: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
aaa0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
aab0: 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
aac0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
aad0: 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
aae0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
aaf0: 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20  tion was.**     
ab00: 20 20 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a       created..**
ab10: 0a 2a 2a 20 7b 46 31 32 32 36 33 7d 20 53 74 61  .** {F12263} Sta
ab20: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
ab30: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
ab40: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
ab50: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
ab60: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
ab70: 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
ab80: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
ab90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
aba0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
abb0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 0a 2a 2a 20  hanges()].**.** 
abc0: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
abd0: 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20 61  ** {U12264} If a
abe0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
abf0: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
ac00: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
ac10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
ac20: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
ac30: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
ac40: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
ac50: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
ac60: 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  alue .**        
ac70: 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
ac80: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
ac90: 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  unmeaningful..*/
aca0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
acb0: 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
acc0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
acd0: 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
ace0: 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
acf0: 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a  Query {F12270}.*
ad00: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
ad10: 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
ad20: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
ad30: 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
ad40: 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
ad50: 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
ad60: 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
ad70: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
ad80: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
ad90: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
ada0: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
adb0: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
adc0: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
add0: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
ade0: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
adf0: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
ae00: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
ae10: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
ae20: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
ae30: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
ae40: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
ae50: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
ae60: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
ae70: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
ae80: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
ae90: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
aea0: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
aeb0: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
aec0: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64  routine with a d
aed0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
aee0: 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  on that.** is cl
aef0: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
af00: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
af10: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
af20: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
af30: 20 61 6e 20 53 51 4c 20 69 73 20 76 65 72 79 20   an SQL is very 
af40: 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
af50: 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
af60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
af70: 70 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  pt().** is calle
af80: 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
af90: 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
afa0: 6f 72 74 75 6e 69 74 79 20 74 6f 20 62 65 20 69  ortunity to be i
afb0: 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49  nterrupted..** I
afc0: 74 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  t might continue
afd0: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
afe0: 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  ** An SQL operat
aff0: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
b000: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
b010: 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  urn.** [SQLITE_I
b020: 4e 54 45 52 52 55 50 54 5d 2e 20 20 49 66 20 74  NTERRUPT].  If t
b030: 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
b040: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
b050: 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50  an.** INSERT, UP
b060: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
b070: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
b080: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
b090: 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e  action, .** then
b0a0: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
b0b0: 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  saction will be 
b0c0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
b0d0: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41 20  matically..** A 
b0e0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b0f0: 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
b100: 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
b110: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
b120: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
b130: 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
b140: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
b150: 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
b160: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
b170: 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
b180: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
b190: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72  terface will for
b1a0: 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a  ce all running.*
b1b0: 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73  *          SQL s
b1c0: 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
b1d0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
b1e0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
b1f0: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
b200: 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72     to halt after
b210: 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d   processing at m
b220: 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e  ost one addition
b230: 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20  al row of.**    
b240: 20 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a 0a 2a        data..**.*
b250: 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53  * {F12272} Any S
b260: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
b270: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
b280: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   by [sqlite3_int
b290: 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
b2a0: 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72        will retur
b2b0: 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
b2c0: 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  UPT]..**.** LIMI
b2d0: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
b2e0: 55 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64  U12279} If the d
b2f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b300: 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
b310: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
b320: 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  pt()].**        
b330: 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65    is running the
b340: 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
b350: 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
b360: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
b370: 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
b380: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
b390: 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
b3a0: 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
b3b0: 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
b3c0: 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F10510}.**.** 
b3d0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
b3e0: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
b3f0: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
b400: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
b410: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
b420: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
b430: 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d  eems to form com
b440: 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74  plete a SQL stat
b450: 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
b460: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
b470: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
b480: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
b490: 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
b4a0: 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54   for parsing.  T
b4b0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
b4c0: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
b4d0: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
b4e0: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
b4f0: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
b500: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
b510: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
b520: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
b530: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
b540: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
b550: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
b560: 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a   fragment of a.*
b570: 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  * CREATE TRIGGER
b580: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
b590: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
b5a0: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
b5b0: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
b5c0: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
b5d0: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
b5e0: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
b5f0: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
b600: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
b610: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
b620: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
b630: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
b640: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
b650: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
b660: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
b670: 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tor..**.** These
b680: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
b690: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 61   parse the SQL a
b6a0: 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f  nd.** so will no
b6b0: 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
b6c0: 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
b6d0: 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   SQL..**.** INVA
b6e0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
b6f0: 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c 69 74  10511} The sqlit
b700: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e  e3_complete() an
b710: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  d sqlite3_comple
b720: 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  te16() functions
b730: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
b740: 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  urn true (non-ze
b750: 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ro) if and only 
b760: 69 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 20  if the last.**  
b770: 20 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68 69 74          non-whit
b780: 65 73 70 61 63 65 20 74 6f 6b 65 6e 20 69 6e 20  espace token in 
b790: 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
b7a0: 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 0a   semicolon that.
b7b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
b7c0: 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68  ot in between th
b7d0: 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
b7e0: 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
b7f0: 47 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  GER.**          
b800: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
b810: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
b820: 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54 68 65  .** {U10512} The
b830: 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65   input to sqlite
b840: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73  3_complete() mus
b850: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
b860: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
b870: 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e     UTF-8 string.
b880: 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20  .**.** {U10513} 
b890: 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c  The input to sql
b8a0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
b8b0: 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ) must be a zero
b8c0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
b8d0: 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73          UTF-16 s
b8e0: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
b8f0: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
b900: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
b910: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
b920: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
b930: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
b940: 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
b950: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b960: 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
b970: 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
b980: 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
b990: 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F12310}.**.** 
b9a0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65  This routine ide
b9b0: 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61  ntifies a callba
b9c0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
b9d0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69 6e 76   might be.** inv
b9e0: 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
b9f0: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
ba00: 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
ba10: 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68  ase table .** th
ba20: 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
ba30: 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  d or process has
ba40: 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74   locked..** If t
ba50: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
ba60: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
ba70: 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
ba80: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
ba90: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
baa0: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
bab0: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
bac0: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
bad0: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
bae0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
baf0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a  NULL, then the.*
bb00: 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  * callback will 
bb10: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
bb20: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  two arguments.  
bb30: 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  The.** first arg
bb40: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
bb50: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
bb60: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
bb70: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
bb80: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
bb90: 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  nt to this routi
bba0: 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ne.  The second 
bbb0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
bbc0: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68  he handler is th
bbd0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
bbe0: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
bbf0: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
bc00: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
bc10: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
bc20: 6e 74 2e 20 20 20 49 66 20 74 68 65 0a 2a 2a 20  nt.   If the.** 
bc30: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
bc40: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
bc50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
bc60: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
bc70: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
bc80: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
bc90: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
bca0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
bcb0: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
bcc0: 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
bcd0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
bce0: 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
bcf0: 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
bd00: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
bd10: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
bd20: 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
bd30: 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
bd40: 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
bd50: 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
bd60: 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
bd70: 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74  antee that.** it
bd80: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
bd90: 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
bda0: 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a  ock contention..
bdb0: 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  ** If SQLite det
bdc0: 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
bdd0: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
bde0: 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
bdf0: 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64  ult in.** a dead
be00: 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
be10: 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
be20: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
be30: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
be40: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
be50: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
be60: 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
be70: 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
be80: 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
be90: 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
bea0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
beb0: 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
bec0: 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
bed0: 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
bee0: 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
bef0: 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
bf00: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
bf10: 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
bf20: 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
bf30: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
bf40: 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
bf50: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
bf60: 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
bf70: 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
bf80: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
bf90: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
bfa0: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
bfb0: 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
bfc0: 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
bfd0: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
bfe0: 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
bff0: 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
c000: 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
c010: 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
c020: 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
c030: 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
c040: 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
c050: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
c060: 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
c070: 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
c080: 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
c090: 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
c0a0: 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
c0b0: 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
c0c0: 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
c0d0: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
c0e0: 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
c0f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
c100: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
c110: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
c120: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
c130: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
c140: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
c150: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
c160: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
c170: 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
c180: 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
c190: 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
c1a0: 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
c1b0: 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
c1c0: 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
c1d0: 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
c1e0: 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
c1f0: 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
c200: 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
c210: 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
c220: 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
c230: 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
c240: 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
c250: 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
c260: 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
c270: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
c280: 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
c290: 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
c2a0: 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49  t.** readers.  I
c2b0: 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
c2c0: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
c2d0: 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
c2e0: 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
c2f0: 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
c300: 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
c310: 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
c320: 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
c330: 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
c340: 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
c350: 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
c360: 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
c370: 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
c380: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
c390: 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f  .  This error co
c3a0: 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
c3b0: 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
c3c0: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
c3d0: 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
c3e0: 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
c3f0: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  ="http://www.sql
c400: 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f  ite.org/cvstrac/
c410: 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
c420: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
c430: 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
c440: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
c450: 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
c460: 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
c470: 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
c480: 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
c490: 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65 20 63  ..**..** There c
c4a0: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
c4b0: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
c4c0: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
c4d0: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
c4e0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69  nnection.  Setti
c4f0: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
c500: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
c510: 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a   previous one. .
c520: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  ** Note that cal
c530: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
c540: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69  sy_timeout()] wi
c550: 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
c560: 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79  lear.** the busy
c570: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
c580: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
c590: 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b  * {F12311} The [
c5a0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
c5b0: 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  dler()] function
c5c0: 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 62 75   replaces the bu
c5d0: 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20  sy handler.**   
c5e0: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
c5f0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
c600: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
c610: 69 66 69 65 64 20 62 79 20 74 68 65 20 31 73 74  ified by the 1st
c620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
c630: 61 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e 65  ameter with a ne
c640: 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  w busy handler i
c650: 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
c660: 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20   2nd and 3rd.** 
c670: 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
c680: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ers..**.** {F123
c690: 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  12} The default 
c6a0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
c6b0: 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
c6c0: 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c  nnections is NUL
c6d0: 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34  L..**.** {F12314
c6e0: 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  } When two or mo
c6f0: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
c700: 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61 20 63  ection share a c
c710: 6f 6d 6d 6f 6e 20 63 61 63 68 65 2c 0a 2a 2a 20  ommon cache,.** 
c720: 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73           the bus
c730: 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
c740: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c750: 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20  ction currently 
c760: 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
c770: 20 20 74 68 65 20 63 61 63 68 65 20 69 73 20 69    the cache is i
c780: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
c790: 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73  cache encounters
c7a0: 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b   a lock..**.** {
c7b0: 46 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73  F12316} If a bus
c7c0: 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
c7d0: 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ck returns zero,
c7e0: 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65   then the SQLite
c7f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
c800: 65 72 66 61 63 65 20 74 68 61 74 20 70 72 6f 76  erface that prov
c810: 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67  oked the locking
c820: 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75   event will retu
c830: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  rn.**          [
c840: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
c850: 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51 4c  .** {F12318} SQL
c860: 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73  ite will invokes
c870: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c880: 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
c890: 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 20 20 20  ent which.**    
c8a0: 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79        are a copy
c8b0: 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20   of the pointer 
c8c0: 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
c8d0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
c8e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c8f0: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
c900: 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e  er()] and a coun
c910: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
c920: 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20  of prior.**     
c930: 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73       invocations
c940: 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e   of the busy han
c950: 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d  dler for the sam
c960: 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
c970: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
c980: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31  NS:.**.** {U1231
c990: 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  9} A busy handle
c9a0: 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  r should not cal
c9b0: 6c 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  l close the data
c9c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
c9d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 70  **          or p
c9e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
c9f0: 74 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  t that invoked t
ca00: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
ca10: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
ca20: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
ca30: 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
ca40: 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
ca50: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ca60: 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
ca70: 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a  meout {F12340}.*
ca80: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
ca90: 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
caa0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
cab0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a 2a   busy handler].*
cac0: 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f  * that sleeps fo
cad0: 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61  r a while when a
cae0: 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  .** table is loc
caf0: 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
cb00: 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  r will sleep mul
cb10: 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
cb20: 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22  l .** at least "
cb30: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
cb40: 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76   of sleeping hav
cb50: 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31  e been done. {F1
cb60: 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22  2343} After.** "
cb70: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
cb80: 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68   of sleeping, th
cb90: 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
cba0: 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75  s 0 which.** cau
cbb0: 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
cbc0: 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b  p()] to return [
cbd0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
cbe0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
cbf0: 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
cc00: 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
cc10: 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
cc20: 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
cc30: 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
cc40: 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
cc50: 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
cc60: 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
cc70: 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
cc80: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
cc90: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
cca0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
ccb0: 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65  tion.  If anothe
ccc0: 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  r busy handler w
ccd0: 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20  as defined  .** 
cce0: 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
ccf0: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
cd00: 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
cd10: 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
cd20: 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
cd30: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
cd40: 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eared..**.** INV
cd50: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
cd60: 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F12341} The [sql
cd70: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
cd80: 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76  t()] function ov
cd90: 65 72 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f  errides any prio
cda0: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
cdb0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
cdc0: 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  out()] or [sqlit
cdd0: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
cde0: 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  )] setting.**   
cdf0: 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
ce00: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
ce10: 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ection..**.** {F
ce20: 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e  12343} If the 2n
ce30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
ce40: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
ce50: 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20  eout()] is less 
ce60: 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
ce70: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
ce80: 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79  o, then the busy
ce90: 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
cea0: 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20  red so that.**  
ceb0: 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73          all subs
cec0: 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65  equent locking e
ced0: 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c  vents immediatel
cee0: 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  y return [SQLITE
cef0: 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _BUSY]..**.** {F
cf00: 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e  12344} If the 2n
cf10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
cf20: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
cf30: 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73  eout()] is a pos
cf40: 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  itive.**        
cf50: 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e    number N, then
cf60: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
cf70: 69 73 20 73 65 74 20 74 68 61 74 20 72 65 70 65  is set that repe
cf80: 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
cf90: 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
cfa0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
cfb0: 74 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  the VFS interfac
cfc0: 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  e until either t
cfd0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  he.**          l
cfe0: 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
cff0: 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
d000: 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65  ve sleep time re
d010: 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20  ported back.**  
d020: 20 20 20 20 20 20 20 20 62 79 20 78 53 6c 65 65          by xSlee
d030: 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
d040: 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
d050: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
d060: 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
d070: 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
d080: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
d090: 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
d0a0: 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
d0b0: 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a  ries {F12370}.**
d0c0: 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
d0d0: 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
d0e0: 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
d0f0: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
d100: 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
d110: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
d120: 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
d130: 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
d140: 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
d150: 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
d160: 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
d170: 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
d180: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
d190: 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
d1a0: 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
d1b0: 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
d1c0: 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
d1d0: 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
d1e0: 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
d1f0: 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
d200: 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
d210: 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
d220: 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
d230: 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
d240: 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
d250: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
d260: 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
d270: 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
d280: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
d290: 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
d2a0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
d2b0: 46 2d 38 20 73 74 72 69 6e 67 73 2e 20 20 54 68  F-8 strings.  Th
d2c0: 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
d2d0: 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
d2e0: 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68 65 20  array.  .** The 
d2f0: 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
d300: 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f 2d 74   point to zero-t
d310: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
d320: 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e 74 61  s that .** conta
d330: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
d340: 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
d350: 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
d360: 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
d370: 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
d380: 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65  .  NULL.** value
d390: 73 20 61 72 65 20 67 69 76 65 20 61 20 4e 55 4c  s are give a NUL
d3a0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c 6c 20  L pointer.  All 
d3b0: 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
d3c0: 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55 54 46   in.** their UTF
d3d0: 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
d3e0: 65 64 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ed string repres
d3f0: 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
d400: 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
d410: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
d420: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
d430: 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
d440: 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65 20 6f  onsists of one o
d450: 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
d460: 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
d470: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
d480: 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
d490: 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
d4a0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
d4b0: 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
d4c0: 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
d4d0: 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
d4e0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
d4f0: 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
d500: 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
d510: 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
d520: 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
d530: 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
d540: 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
d550: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
d560: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
d570: 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
d580: 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
d590: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d5a0: 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
d5b0: 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
d5c0: 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
d5d0: 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
d5e0: 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
d5f0: 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
d600: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
d610: 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
d620: 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
d630: 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
d640: 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
d650: 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
d660: 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
d670: 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
d680: 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
d690: 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
d6a0: 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
d6b0: 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
d6c0: 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
d6d0: 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
d6e0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
d6f0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d700: 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
d710: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
d720: 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
d730: 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
d740: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
d750: 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
d760: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d770: 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
d780: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d790: 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
d7a0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d7b0: 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
d7c0: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d7d0: 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
d7e0: 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
d7f0: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
d800: 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
d810: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
d820: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
d830: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
d840: 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
d850: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
d860: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
d870: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
d880: 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
d890: 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
d8a0: 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
d8b0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
d8c0: 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
d8d0: 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
d8e0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
d8f0: 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
d900: 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
d910: 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
d920: 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
d930: 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
d940: 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
d950: 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  ld .** pass the 
d960: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
d970: 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
d980: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
d990: 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  e() in order to 
d9a0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
d9b0: 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
d9c0: 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61  malloc-ed.  Beca
d9d0: 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
d9e0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
d9f0: 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
da00: 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
da10: 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
da20: 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
da30: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
da40: 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
da50: 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
da60: 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a 20  ctly.  Only .** 
da70: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
da80: 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
da90: 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
daa0: 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
dab0: 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
dac0: 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
dad0: 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
dae0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
daf0: 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
db00: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
db10: 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
db20: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
db30: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
db40: 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
db50: 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
db60: 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
db70: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
db80: 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
db90: 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
dba0: 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
dbb0: 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
dbc0: 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
dbd0: 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
dbe0: 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
dbf0: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
dc00: 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
dc10: 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
dc20: 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
dc30: 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
dc40: 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
dc50: 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
dc60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
dc70: 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  sg()]..**.** INV
dc80: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
dc90: 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71  F12371} If a [sq
dca0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
dcb0: 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72  )] fails a memor
dcc0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  y allocation, th
dcd0: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  en.**          i
dce0: 74 20 66 72 65 65 73 20 74 68 65 20 72 65 73 75  t frees the resu
dcf0: 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63  lt table under c
dd00: 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f  onstruction, abo
dd10: 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
dd20: 20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f      query in pro
dd30: 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e 79 20  cess, skips any 
dd40: 73 75 62 73 65 71 75 65 6e 74 20 71 75 65 72 69  subsequent queri
dd50: 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  es, sets the.** 
dd60: 20 20 20 20 20 20 20 20 20 2a 72 65 73 75 6c 74           *result
dd70: 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72  p output pointer
dd80: 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74   to NULL and ret
dd90: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  urns [SQLITE_NOM
dda0: 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  EM]..**.** {F123
ddb0: 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c 75  73} If the ncolu
ddc0: 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  mn parameter to 
ddd0: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
dde0: 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
ddf0: 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
de00: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  en [sqlite3_get_
de10: 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74  table()] write t
de20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
de30: 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  umns in the.**  
de40: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
de50: 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
de60: 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66  into *ncolumn if
de70: 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a   the query is.**
de80: 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73            succes
de90: 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e  sful (if the fun
dea0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51  ction returns SQ
deb0: 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK)..**.** 
dec0: 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68 65 20  {F12374} If the 
ded0: 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74  nrow parameter t
dee0: 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
def0: 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
df00: 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
df10: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65  then [sqlite3_ge
df20: 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65  t_table()] write
df30: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
df40: 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
df50: 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
df60: 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
df70: 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65  nto *nrow if the
df80: 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20   query is.**    
df90: 20 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c        successful
dfa0: 20 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f   (if the functio
dfb0: 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  n returns SQLITE
dfc0: 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  _OK)..**.** {F12
dfd0: 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  376} The [sqlite
dfe0: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
dff0: 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73  unction sets its
e000: 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 0a   *ncolumn value.
e010: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
e020: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
e030: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
e040: 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
e050: 65 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ery in the.**   
e060: 20 20 20 20 20 20 20 73 71 6c 20 70 61 72 61 6d         sql param
e070: 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f  eter, or to zero
e080: 20 69 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   if the query in
e090: 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74   sql has an empt
e0a0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
e0b0: 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  sult set..*/.int
e0c0: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
e0d0: 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  le(.  sqlite3*, 
e0e0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
e0f0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
e100: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
e110: 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51  *sql,      /* SQ
e120: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
e130: 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
e140: 52 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20  Result,      /* 
e150: 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
e160: 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  uery */.  int *n
e170: 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20  row,            
e180: 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
e190: 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
e1a0: 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
e1b0: 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  ncolumn,        
e1c0: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
e1d0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
e1e0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
e1f0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
e200: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
e210: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
e220: 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
e230: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
e240: 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
e250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
e260: 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
e270: 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
e280: 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a  s {F17400}.**.**
e290: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
e2a0: 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f  are workalikes o
e2b0: 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
e2c0: 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
e2d0: 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
e2e0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
e2f0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ary..**.** The s
e300: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
e310: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
e320: 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
e330: 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
e340: 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
e350: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
e360: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
e370: 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
e380: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
e390: 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
e3a0: 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
e3b0: 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
e3c0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
e3d0: 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
e3e0: 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
e3f0: 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
e400: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
e410: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
e420: 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
e430: 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
e440: 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
e450: 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69  g..**.** In sqli
e460: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
e470: 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
e480: 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
e490: 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
e4a0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
e4b0: 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
e4c0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
e4d0: 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
e4e0: 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
e4f0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
e500: 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
e510: 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
e520: 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
e530: 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
e540: 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
e550: 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
e560: 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
e570: 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69  snprintf().  Thi
e580: 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
e590: 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
e5a0: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
e5b0: 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
e5c0: 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
e5d0: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
e5e0: 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74    Note also that
e5f0: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
e600: 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
e610: 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
e620: 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
e630: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
e640: 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
e650: 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
e660: 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20  nto the buffer. 
e670: 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
e680: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
e690: 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
e6a0: 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
e6b0: 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
e6c0: 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
e6d0: 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
e6e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e6f0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
e700: 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
e710: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
e720: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
e730: 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20  *.** As long as 
e740: 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
e750: 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
e760: 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
e770: 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
e780: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
e790: 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
e7a0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
e7b0: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
e7c0: 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
e7d0: 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
e7e0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
e7f0: 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
e800: 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
e810: 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
e820: 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
e830: 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
e840: 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
e850: 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
e860: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
e870: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
e880: 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
e890: 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
e8a0: 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
e8b0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
e8c0: 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
e8d0: 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
e8e0: 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
e8f0: 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
e900: 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
e910: 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
e920: 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
e930: 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
e940: 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
e950: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
e960: 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
e970: 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
e980: 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
e990: 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
e9a0: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
e9b0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
e9c0: 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
e9d0: 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
e9e0: 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
e9f0: 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
ea00: 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
ea10: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
ea20: 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
ea30: 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
ea40: 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
ea50: 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
ea60: 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
ea70: 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
ea80: 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
ea90: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
eaa0: 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72 69  le, so some stri
eab0: 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e 74  ng variable cont
eac0: 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
ead0: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
eae0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
eaf0: 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
eb00: 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
eb10: 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
eb20: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
eb30: 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
eb40: 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
eb50: 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
eb60: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
eb70: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
eb80: 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
eb90: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
eba0: 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
ebb0: 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
ebc0: 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
ebd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
ebe0: 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
ebf0: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
ec00: 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
ec10: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
ec20: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
ec30: 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
ec40: 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
ec50: 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
ec60: 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
ec70: 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
ec80: 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
ec90: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
eca0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
ecb0: 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
ecc0: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
ecd0: 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
ece0: 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
ecf0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
ed00: 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
ed10: 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
ed20: 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
ed30: 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
ed40: 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
ed50: 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
ed60: 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
ed70: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
ed80: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
ed90: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
eda0: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
edb0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
edc0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
edd0: 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
ede0: 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
edf0: 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
ee00: 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
ee10: 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  .** should alway
ee20: 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
ee30: 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
ee40: 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
ee50: 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74  a string .** lit
ee60: 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
ee70: 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
ee80: 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
ee90: 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
eea0: 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
eeb0: 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
eec0: 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
eed0: 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20  ing.  Or if the 
eee0: 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
eef0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73   argument.** lis
ef00: 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
ef10: 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
ef20: 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
ef30: 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e  LL" (without sin
ef40: 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69  gle.** quotes) i
ef50: 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
ef60: 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  Q option. {END} 
ef70: 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
ef80: 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
ef90: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
efa0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
efb0: 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
efc0: 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
efd0: 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
efe0: 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
eff0: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
f000: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
f010: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
f020: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
f030: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
f040: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
f050: 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
f060: 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
f070: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
f080: 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
f090: 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
f0a0: 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
f0b0: 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
f0c0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
f0d0: 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
f0e0: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
f0f0: 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
f100: 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
f110: 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
f120: 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
f130: 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
f140: 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
f150: 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
f160: 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
f170: 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
f180: 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ring. {END}.**.*
f190: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
f1a0: 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54 68  .** {F17403}  Th
f1b0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  e [sqlite3_mprin
f1c0: 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  tf()] and [sqlit
f1d0: 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69  e3_vmprintf()] i
f1e0: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20  nterfaces.**    
f1f0: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69         return ei
f200: 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f  ther pointers to
f210: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
f220: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68   UTF-8 strings h
f230: 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  eld in.**       
f240: 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69      memory obtai
f250: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
f260: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e  3_malloc()] or N
f270: 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a  ULL pointers if.
f280: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63  **           a c
f290: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
f2a0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e  malloc()] fails.
f2b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20  .**.** {F17406} 
f2c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
f2d0: 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
f2e0: 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72  ace writes a zer
f2f0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
f300: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
f310: 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20  string into the 
f320: 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74  buffer pointed t
f330: 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
f340: 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
f350: 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20         provided 
f360: 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70  that the first p
f370: 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61  arameter is grea
f380: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a  ter than zero..*
f390: 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20 54  *.** {F17407}  T
f3a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
f3b0: 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
f3c0: 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65  e does not write
f3d0: 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  s slots of.**   
f3e0: 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
f3f0: 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
f400: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
f410: 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
f420: 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
f430: 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
f440: 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
f450: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f460: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
f470: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
f480: 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
f490: 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
f4a0: 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
f4b0: 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
f4c0: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a  fication..**   .
f4d0: 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
f4e0: 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
f4f0: 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
f500: 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
f510: 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
f520: 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
f530: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
f540: 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
f550: 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
f560: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
f570: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
f580: 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30  Subsystem {F1730
f590: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0}.**.** The SQL
f5a0: 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74  ite core  uses t
f5b0: 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
f5c0: 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
f5d0: 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
f5e0: 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
f5f0: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
f600: 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
f610: 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
f620: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
f630: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f640: 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
f650: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
f660: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 56 46  he.** windows VF
f670: 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
f680: 6c 6c 6f 63 20 61 6e 64 20 66 72 65 65 20 66 6f  lloc and free fo
f690: 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
f6a0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
f6b0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
f6c0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
f6d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
f6e0: 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
f6f0: 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
f700: 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
f710: 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
f720: 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  eter..** If sqli
f730: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
f740: 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
f750: 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
f760: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
f770: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
f780: 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70  inter.  If the p
f790: 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
f7a0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f7b0: 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
f7c0: 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
f7d0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
f7e0: 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
f7f0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  inter..**.** Cal
f800: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
f810: 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
f820: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
f830: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
f840: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
f850: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f860: 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
f870: 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
f880: 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
f890: 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69  eused.  The sqli
f8a0: 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
f8b0: 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
f8c0: 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
f8d0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
f8e0: 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
f8f0: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
f900: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
f910: 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
f920: 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
f930: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
f940: 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
f950: 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
f960: 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
f970: 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
f980: 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
f990: 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
f9a0: 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
f9b0: 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
f9c0: 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
f9d0: 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
f9e0: 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
f9f0: 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
fa00: 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
fa10: 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
fa20: 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
fa30: 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
fa40: 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
fa50: 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
fa60: 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
fa70: 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
fa80: 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a  te3_free()..**.*
fa90: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
faa0: 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
fab0: 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
fac0: 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
fad0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fae0: 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
faf0: 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
fb00: 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
fb10: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
fb20: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
fb30: 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
fb40: 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
fb50: 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
fb60: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
fb70: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
fb80: 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
fb90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
fba0: 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
fbb0: 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
fbc0: 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
fbd0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
fbe0: 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
fbf0: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
fc00: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
fc10: 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
fc20: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
fc30: 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
fc40: 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
fc50: 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
fc60: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
fc70: 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
fc80: 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
fc90: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
fca0: 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
fcb0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
fcc0: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
fcd0: 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65 33 5f  c()..** Sqlite3_
fce0: 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
fcf0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
fd00: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fd10: 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
fd20: 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
fd30: 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
fd40: 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
fd50: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
fd60: 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
fd70: 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
fd80: 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
fd90: 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
fda0: 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
fdb0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
fdc0: 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
fdd0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
fde0: 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
fdf0: 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
fe00: 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
fe10: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
fe20: 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
fe30: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
fe40: 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
fe50: 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
fe60: 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
fe70: 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
fe80: 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
fe90: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
fea0: 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
feb0: 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
fec0: 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
fed0: 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
fee0: 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
fef0: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
ff00: 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
ff10: 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
ff20: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ff30: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
ff40: 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  es the malloc(),
ff50: 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e   realloc().** an
ff60: 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
ff70: 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
ff80: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b 46 31  d C library. {F1
ff90: 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
ffa0: 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  f .** SQLite is 
ffb0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ffc0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72  e following C pr
ffd0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
ffe0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
fff0: 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52  te> SQLITE_MEMOR
10000 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69  Y_SIZE=<i>NNN</i
10010 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  > </blockquote>.
10020 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e 4e  **.** where <i>N
10030 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e 74  NN</i> is an int
10040 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  eger, then SQLit
10050 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
10060 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61 74  c.** array of at
10070 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69   least <i>NNN</i
10080 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
10090 61 6e 64 20 75 73 65 20 74 68 61 74 20 61 72 72  and use that arr
100a0 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  ay.** for all of
100b0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
100c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
100d0 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
100e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72  itional.** memor
100f0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
10100 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
10110 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
10120 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
10130 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
10140 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
10150 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
10160 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
10170 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
10180 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
10190 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
101a0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
101b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
101c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
101d0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
101e0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
101f0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
10200 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
10210 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
10220 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
10230 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  e.** used..**.**
10240 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f 53 20   The windows OS 
10250 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
10260 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
10270 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
10280 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
10290 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
102a0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
102b0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
102c0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
102d0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
102e0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
102f0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
10300 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
10310 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar windows.** i
10320 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
10330 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10340 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
10350 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
10360 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
10370 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
10380 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
10390 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
103a0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
103b0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
103c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
103d0 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b   {F17303}  The [
103e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
103f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10400 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
10410 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20 20 20  inter to .**    
10420 20 20 20 20 20 20 20 6e 65 77 6c 79 20 63 68 65         newly che
10430 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f  cked-out block o
10440 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
10450 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
10460 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
10470 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
10480 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  , .**           
10490 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
104a0 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
104b0 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68  le to fulfill th
104c0 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a  e request..**.**
104d0 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b   {F17304}  The [
104e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
104f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10500 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
10510 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ter if.**       
10520 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68      N is less th
10530 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
10540 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ero..**.** {F173
10550 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  05}  The [sqlite
10560 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72  3_free(P)] inter
10570 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65  face releases me
10580 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a  mory previously.
10590 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
105a0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
105b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
105c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
105d0 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
105e0 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61     making it ava
105f0 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65  ilable for reuse
10600 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36 7d  ..**.** {F17306}
10610 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
10620 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d  ite3_free(NULL)]
10630 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
10640 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  o-op..**.** {F17
10650 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  310}  A call to 
10660 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10670 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61  (0,N)] is equiva
10680 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
10690 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
106a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
106b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
106c0 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  2}  A call to [s
106d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
106e0 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,0)] is equivale
106f0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
10700 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
10710 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a  lite3_free(P)]..
10720 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20  **.** {F17315}  
10730 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
10740 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61  uses [sqlite3_ma
10750 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
10760 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
10770 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b             and [
10780 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
10790 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  for all of its m
107a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
107b0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
107c0 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e    deallocation n
107d0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  eeds..**.** {F17
107e0 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  318}  The [sqlit
107f0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
10800 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
10810 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
10820 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
10830 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63   to a block of c
10840 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72  hecked-out memor
10850 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  y of at least N 
10860 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a  bytes in size.**
10870 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
10880 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
10890 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  d, or a NULL poi
108a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  nter..**.** {F17
108b0 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  321}  When [sqli
108c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
108d0 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
108e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
108f0 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
10900 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66      copies the f
10910 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20  irst K bytes of 
10920 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69  content from P i
10930 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20 61 6c  nto the newly al
10940 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
10950 20 20 20 20 20 77 68 65 72 65 20 4b 20 69 73 20       where K is 
10960 74 68 65 20 6c 65 73 73 6f 72 20 6f 66 20 4e 20  the lessor of N 
10970 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
10980 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
10990 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20 57 68  .** {F17322}  Wh
109a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
109b0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
109c0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
109d0 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
109e0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
109f0 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
10a00 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 33  P..**.** {F17323
10a10 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
10a20 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
10a30 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
10a40 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
10a50 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
10a60 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
10a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
10a80 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
10a90 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
10aa0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
10ab0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10ac0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
10ad0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
10ae0 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
10af0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
10b00 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  e a pointer obta
10b10 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
10b20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  r.**           i
10b30 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
10b40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
10b50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
10b60 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 73 0a  loc()] that has.
10b70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
10b80 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
10b90 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d 20 20  **.** {U17351}  
10ba0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10bb0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
10bc0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
10bd0 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  of .**          
10be0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
10bf0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
10c00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
10c10 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10c20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10c30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
10c40 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a  alloc()]..**.*/.
10c50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
10c60 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
10c70 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
10c80 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
10c90 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
10ca0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
10cb0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
10cc0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
10cd0 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a  tics {F17370}.**
10ce0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
10cf0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
10d00 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
10d10 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
10d20 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
10d30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10d40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
10d50 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
10d60 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
10d70 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10d80 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
10d90 69 6e 63 6c 75 64 65 64 20 77 69 74 68 69 6e 20  included within 
10da0 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a  the SQLite..**.*
10db0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10dc0 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65  .** {F17371} The
10dd0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10de0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
10df0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
10e00 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
10e10 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  of bytes of memo
10e20 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
10e30 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20 20 20  standing .**    
10e40 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65 64 20        (malloced 
10e50 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
10e60 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54  **.** {F17373} T
10e70 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
10e80 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
10e90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10ea0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
10eb0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
10ec0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10ed0 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20 20 20  _used()] .**    
10ee0 20 20 20 20 20 20 73 69 6e 63 65 20 74 68 65 20        since the 
10ef0 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 77  highwater mark w
10f00 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
10f10 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20 54 68  *.** {F17374} Th
10f20 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
10f30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
10f40 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
10f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10f60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10f70 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
10f80 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
10f90 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64  *          added
10fa0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
10fb0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
10fc0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
10fd0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
10fe0 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72      but not over
10ff0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
11000 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
11010 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
11020 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
11030 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
11040 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
11050 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46   call..** .** {F
11060 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
11070 79 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  y highwater mark
11080 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
11090 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
110a0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
110b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
110c0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
110d0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
110e0 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
110f0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
11100 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
11110 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c  s true.  The val
11120 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
11130 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
11140 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
11150 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
11160 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 0a 2a  highwater mark.*
11170 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72  *          prior
11180 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
11190 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
111a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
111b0 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
111c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
111d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
111e0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
111f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11200 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
11210 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
11220 72 20 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a  r {F17390}.**.**
11230 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
11240 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
11250 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
11260 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
11270 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
11280 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52   select random R
11290 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72  OWIDs when inser
112a0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
112b0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
112c0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
112d0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
112e0 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20  ossible ROWID.  
112f0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
11300 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
11310 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
11320 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
11330 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
11340 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
11350 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
11360 6c 69 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  liations to acce
11370 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
11380 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
11390 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
113a0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
113b0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
113c0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
113d0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
113e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
113f0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
11400 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
11410 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
11420 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
11430 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
11440 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
11450 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
11460 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
11470 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
11480 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
11490 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
114a0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
114b0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
114c0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
114d0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
114e0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
114f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
11500 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
11510 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11520 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
11530 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
11540 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
11550 2a 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68  *.** {F17392} Th
11560 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  e [sqlite3_rando
11570 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65  mness(N,P)] inte
11580 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
11590 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
115a0 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79      high-quality
115b0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
115c0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
115d0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
115e0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
115f0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
11600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
11610 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
11620 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
11630 63 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a  cks {F12500}.**.
11640 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
11650 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68  registers a auth
11660 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11670 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
11680 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
11690 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
116a0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
116b0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  t argument..** T
116c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
116d0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
116e0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
116f0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
11700 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
11710 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
11720 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
11730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11740 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
11750 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
11760 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
11770 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
11780 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
11790 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
117a0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
117b0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
117c0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
117d0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
117e0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
117f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11800 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
11810 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
11820 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
11830 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
11840 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11850 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
11860 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
11870 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
11880 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
11890 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
118a0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
118b0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
118c0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
118d0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
118e0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
118f0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
11900 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
11910 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
11920 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
11930 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
11940 65 72 72 6f 72 2e 20 20 20 49 66 20 74 68 65 20  error.   If the 
11950 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
11960 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
11970 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
11980 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
11990 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
119a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
119b0 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  Y].** then [sqli
119c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
119d0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
119e0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
119f0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
11a00 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
11a10 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
11a20 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
11a30 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
11a40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
11a50 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
11a60 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
11a70 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
11a80 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62    When the callb
11a90 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
11aa0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
11ab0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
11ac0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
11ad0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
11ae0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
11af0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
11b00 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
11b10 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
11b20 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
11b30 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
11b40 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
11b50 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51  izer code is [SQ
11b60 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
11b70 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
11b80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
11b90 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
11ba0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
11bb0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
11bc0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
11bd0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
11be0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
11bf0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
11c00 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
11c10 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
11c20 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
11c30 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
11c40 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
11c50 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
11c60 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
11c70 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
11c80 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
11c90 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
11ca0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
11cb0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a  of a table..**.*
11cc0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
11cd0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
11ce0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11cf0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
11d00 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
11d10 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
11d20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
11d30 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
11d40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
11d50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
11d60 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
11d70 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54  teger .** [SQLIT
11d80 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
11d90 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
11da0 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
11db0 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f  lar action.** to
11dc0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
11dd0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
11de0 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
11df0 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
11e00 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
11e10 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
11e20 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a  s that contain .
11e30 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  ** additional de
11e40 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
11e50 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
11e60 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  horized..**.** A
11e70 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
11e80 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
11e90 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
11ea0 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
11eb0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
11ec0 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73  n untrusted.** s
11ed0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
11ee0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
11ef0 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20  atements do not 
11f00 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
11f10 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20  ta.** that they 
11f20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
11f30 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
11f40 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20  they do not try 
11f50 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61  to.** execute ma
11f60 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
11f70 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
11f80 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
11f90 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
11fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
11fb0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
11fc0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
11fd0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
11fe0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
11ff0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
12000 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
12010 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
12020 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
12030 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
12040 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
12050 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
12060 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
12070 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
12080 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
12090 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
120a0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
120b0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
120c0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
120d0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
120e0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
120f0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
12100 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
12110 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
12120 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
12130 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
12140 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
12150 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
12160 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
12170 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
12180 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
12190 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
121a0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
121b0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
121c0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
121d0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
121e0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
121f0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
12200 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
12210 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
12220 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
12230 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
12240 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
12250 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
12260 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
12270 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
12280 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
12290 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73  vious call.  Dis
122a0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
122b0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
122c0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
122d0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
122e0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
122f0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
12300 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
12310 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
12320 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
12330 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20  only during .** 
12340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
12350 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
12360 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
12370 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
12380 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
12390 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
123a0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
123b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  step()]..**.** I
123c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
123d0 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73   {F12501} The [s
123e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
123f0 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e  rizer(D,...)] in
12400 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
12410 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
12420 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
12430 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73  ack with databas
12440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
12450 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54  **.** {F12502} T
12460 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
12470 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
12480 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
12490 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  nts are.**      
124a0 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c      being compil
124b0 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33  ed.**.** {F12503
124c0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
124d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
124e0 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f  urns any value o
124f0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
12500 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
12510 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
12520 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
12530 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ENY] then.**    
12540 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
12550 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
12560 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
12570 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a  all that caused.
12580 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12590 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
125a0 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
125b0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a   fail with an.**
125c0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
125d0 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
125e0 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  ode and an appro
125f0 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
12600 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  sage..**.** {F12
12610 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75  504} When the au
12620 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12630 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
12640 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61  E_OK], the opera
12650 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
12660 20 64 65 73 63 72 69 62 65 64 20 69 73 20 63 6f   described is co
12670 64 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a  ded normally..**
12680 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68 65  .** {F12505} Whe
12690 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  n the authorizer
126a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
126b0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
126c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
126d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
126e0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
126f0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
12700 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20  caused the.**   
12710 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
12720 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
12730 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20  n shall fail.** 
12740 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e           with an
12750 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12760 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
12770 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  n error message.
12780 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c  **          expl
12790 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65  aining that acce
127a0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a  ss is denied..**
127b0 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66 20  .** {F12506} If 
127c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
127d0 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
127e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
127f0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
12800 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
12810 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  s [SQLITE_READ] 
12820 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  and the authoriz
12830 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
12840 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
12850 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
12860 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  then the prepare
12870 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
12880 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a  onstructed to.**
12890 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74            insert
128a0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
128b0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
128c0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
128d0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20  would have.**   
128e0 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64         been read
128f0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
12900 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
12910 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 37  d..**.** {F12507
12920 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
12930 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
12940 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
12950 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
12960 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
12970 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20  ck) is anything 
12980 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
12990 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a  TE_READ], then.*
129a0 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
129b0 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  urn of [SQLITE_I
129c0 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73  GNORE] has the s
129d0 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53  ame effect as [S
129e0 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a  QLITE_DENY]. .**
129f0 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65  .** {F12510} The
12a00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12a10 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
12a20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
12a30 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
12a40 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70       the third p
12a50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
12a60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12a70 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
12a80 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  face..**.** {F12
12a90 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  511} The second 
12aa0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
12ab0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
12ac0 69 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20 20 20  integer .**     
12ad0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
12ae0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
12af0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
12b00 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
12b10 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
12b20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a    to be authoriz
12b30 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31  ed..**.** {F1251
12b40 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72  2} The third thr
12b50 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
12b60 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
12b70 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20  lback are.**    
12b80 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
12b90 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
12ba0 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 20  at contain .**  
12bb0 20 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e          addition
12bc0 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  al details about
12bd0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
12be0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
12bf0 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63  .** {F12520} Eac
12c00 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
12c10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12c20 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  r()] overrides t
12c30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
12c40 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e  ny previously in
12c50 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a  stalled authoriz
12c60 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  er..**.** {F1252
12c70 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  1} A NULL author
12c80 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
12c90 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
12ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
12cb0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
12cc0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d  ..**.** {F12522}
12cd0 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
12ce0 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
12cf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12d00 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
12d10 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
12d20 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
12d30 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
12d40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
12d50 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
12d60 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
12d70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
12d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
12d90 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
12da0 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a  odes {F12590}.**
12db0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
12dc0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
12dd0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
12de0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
12df0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
12e00 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
12e10 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
12e20 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
12e30 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
12e40 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
12e50 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
12e60 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
12e70 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
12e80 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
12e90 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
12ea0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
12eb0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
12ec0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
12ed0 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
12ee0 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
12ef0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
12f00 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
12f10 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
12f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
12f30 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
12f40 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
12f50 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
12f60 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
12f70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
12f80 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
12f90 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a  Codes {F12550}.*
12fa0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
12fb0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12fc0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
12fd0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
12fe0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
12ff0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
13000 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72  o authorizer cer
13010 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
13020 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
13030 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
13040 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
13050 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
13060 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
13070 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
13080 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
13090 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
130a0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
130b0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
130c0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
130d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
130e0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
130f0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
13100 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
13110 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
13120 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
13130 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69  o be .** authori
13140 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
13150 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
13160 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
13170 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
13180 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
13190 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
131a0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
131b0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
131c0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
131d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
131e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
131f0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
13200 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
13210 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
13220 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
13230 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
13240 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74  , "temp", .** et
13250 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
13260 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61  e.  The 6th para
13270 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
13280 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13290 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
132a0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
132b0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
132c0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
132d0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
132e0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
132f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
13300 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
13310 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  s directly from 
13320 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
13330 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
13340 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
13350 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {F12551} The sec
13360 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
13370 20 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   an .**         
13380 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
13390 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
133a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
133b0 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65  s always an inte
133c0 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
133d0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
133e0 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
133f0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77  that specifies w
13400 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  hat action.**   
13410 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20         is being 
13420 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
13430 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33  * {F12552} The 3
13440 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
13450 65 74 65 72 73 20 74 6f 20 74 68 65 20 0a 2a 2a  eters to the .**
13460 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13470 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
13480 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  r | authorizatio
13490 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  n callback funct
134a0 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion].**         
134b0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
134c0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
134d0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 0a  nding on which .
134e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
134f0 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
13500 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75  rizer code] is u
13510 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
13520 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
13530 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65 20  ** {F12553} The 
13540 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
13550 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
13560 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
13570 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
13580 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
13590 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  is the name.**  
135a0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64          of the d
135b0 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65  atabase (example
135c0 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  : "main", "temp"
135d0 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  , etc.) if appli
135e0 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  cable..**.** {F1
135f0 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61  2554} The 6th pa
13600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
13610 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
13620 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
13630 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
13640 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
13650 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
13660 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d    of the inner-m
13670 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
13680 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
13690 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20  onsible for.**  
136a0 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65          the acce
136b0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
136c0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
136d0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
136e0 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 20  ectly from .**  
136f0 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65          top-leve
13700 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
13710 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
13740 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
13750 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
13760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
13770 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
13780 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
13790 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
137a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
137b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
137c0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
137d0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
137e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
137f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13800 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
13810 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
13820 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
13830 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
13840 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
13850 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
13860 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
13870 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
13880 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
13890 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
138a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
138b0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
138c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
138d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
138e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
138f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
13900 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
13910 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
13920 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13930 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13940 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
13950 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
13960 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
13970 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
13980 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13990 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
139a0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
139b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
139c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
139d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
139e0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
139f0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
13a00 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
13a10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13a20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13a30 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
13a40 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
13a50 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
13a60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13a70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13a80 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
13a90 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
13aa0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13ab0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13ac0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13ad0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
13ae0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
13af0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
13b00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
13b10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13b20 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
13b30 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
13b40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
13b50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13b60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13b70 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
13b80 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
13b90 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
13ba0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
13bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13bc0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
13bd0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
13be0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
13bf0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13c00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
13c10 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
13c20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
13c30 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
13c40 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
13c50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
13c60 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
13c70 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
13c80 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
13c90 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
13cb0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
13cc0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
13cd0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
13ce0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13cf0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
13d00 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
13d10 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
13d20 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
13d30 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
13d40 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
13d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
13d60 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
13d70 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
13d80 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
13d90 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
13da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
13db0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
13dc0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13dd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13de0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
13df0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
13e00 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
13e10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13e20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13e30 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
13e40 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
13e50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13e60 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
13e70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13e80 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
13e90 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
13ea0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
13eb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13ec0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13ed0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
13ee0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
13ef0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
13f00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13f10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13f20 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
13f30 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
13f40 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
13f50 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13f60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13f70 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
13f80 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
13f90 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
13fa0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13fc0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
13fd0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
13fe0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
13ff0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
14000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14010 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
14020 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
14030 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
14040 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
14050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14060 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
14070 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
14080 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
14090 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
140a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
140b0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
140c0 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63      31   /* Func
140d0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  tion Name   NULL
140e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
140f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14100 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
14110 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
14120 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
14130 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
14140 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
14150 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  ing Functions {F
14160 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12280}.**.** The
14170 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
14180 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
14190 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
141a0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
141b0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
141c0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
141d0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
141e0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
141f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
14200 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
14210 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
14220 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
14230 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
14240 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
14250 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
14260 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
14270 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
14280 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
14290 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
142a0 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
142b0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
142c0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
142d0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
142e0 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
142f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
14300 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
14310 72 69 67 67 65 72 73 75 62 70 72 6f 67 72 61 6d  riggersubprogram
14320 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
14330 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
14340 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
14350 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
14360 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
14370 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
14380 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ger..** .** The 
14390 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
143a0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
143b0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
143c0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
143d0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
143e0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
143f0 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   The profile cal
14400 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
14410 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
14420 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
14430 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
14440 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
14450 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
14460 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
14470 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ook to run..**.*
14480 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
14490 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63  ofile() API is c
144a0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
144b0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
144c0 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65   and.** is subje
144d0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
144e0 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74  removal in a fut
144f0 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a  ure release..**.
14500 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72  ** The trigger r
14510 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65  eporting feature
14520 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61   of the trace ca
14530 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64  llback is consid
14540 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65  ered.** experime
14550 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a  ntal and is subj
14560 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
14570 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
14580 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20  re releases..** 
14590 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
145a0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
145b0 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61  also add new tra
145c0 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  ce callback .** 
145d0 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  invocations..**.
145e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
145f0 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68  *.** {F12281} Th
14600 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
14610 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
14620 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
14630 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
14640 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53     whenever an S
14650 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  QL statement fir
14660 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65  st begins to exe
14670 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  cute and.**     
14680 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20       whenever a 
14690 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
146a0 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  am first begins 
146b0 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  to run..**.** {F
146c0 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c  12282} Each call
146d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
146e0 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  ce()] overrides 
146f0 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  the previously.*
14700 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
14710 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c  tered trace call
14720 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
14730 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63  283} A NULL trac
14740 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62  e callback disab
14750 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a  les tracing..**.
14760 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20  ** {F12284} The 
14770 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
14780 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
14790 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
147a0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
147b0 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  e pointer which 
147c0 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75  was the 3rd argu
147d0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
147e0 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _trace()]..**.**
147f0 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65   {F12285} The se
14800 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14810 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
14820 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
14830 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
14840 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
14850 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
14860 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a  original text.**
14870 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
14880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
14890 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20  s it was passed 
148a0 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  into [sqlite3_pr
148b0 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
148c0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
148d0 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e  quivalent, or an
148e0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64   SQL comment ind
148f0 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69  icating the begi
14900 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
14910 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73    of a trigger s
14920 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  ubprogram..**.**
14930 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61   {F12287} The ca
14940 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
14950 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
14960 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
14970 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ] is invoked.** 
14980 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68           as each
14990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
149a0 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  inishes..**.** {
149b0 46 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73  F12288} The firs
149c0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
149d0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
149e0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
149f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14a00 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
14a10 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  o [sqlite3_profi
14a20 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  le()]..**.** {F1
14a30 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64  2289} The second
14a40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
14a50 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
14a60 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
14a70 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
14a80 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
14a90 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74   that contains t
14aa0 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74  he complete text
14ab0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
14ac0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
14ad0 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63  t as it was proc
14ae0 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  essed by [sqlite
14af0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
14b00 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
14b10 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a  he equivalent..*
14b20 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68  *.** {F12290} Th
14b30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
14b40 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
14b50 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e    callback is an
14b60 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20   estimate.**    
14b70 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d        of the num
14b80 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
14b90 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  ds of wall-clock
14ba0 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74   time required t
14bb0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75  o.**          ru
14bc0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
14bd0 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74  ent from start t
14be0 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69  o finish..*/.voi
14bf0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
14c00 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
14c10 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
14c20 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
14c30 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
14c40 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
14c50 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
14c60 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
14c70 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
14c80 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
14c90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14ca0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
14cb0 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ss Callbacks {F1
14cc0 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2910}.**.** This
14cd0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
14ce0 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
14cf0 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
14d00 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
14d10 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
14d20 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
14d30 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
14d40 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
14d50 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
14d60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
14d70 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
14d80 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14d90 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  ].   An example 
14da0 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a  use for this .**
14db0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
14dc0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
14dd0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
14de0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
14df0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
14e00 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
14e10 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
14e20 70 65 72 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  pertion is.** in
14e30 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
14e40 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
14e50 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
14e60 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
14e70 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
14e80 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
14e90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14ea0 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65  .** {F12911} The
14eb0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
14ec0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
14ed0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
14ee0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a  ss_handler()].**
14ef0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
14f00 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
14f10 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
14f20 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
14f30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
14f40 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
14f50 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20  ** {F12912} The 
14f60 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
14f70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
14f80 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
14f90 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  rtual.**        
14fa0 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65    machine opcode
14fb0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
14fc0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14fd0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  t to .**        
14fe0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70    the [sqlite3_p
14ff0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
15000 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67  )] call that reg
15010 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
15020 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
15030 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66  .  <todo>What if
15040 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
15050 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  1?</todo>.**.** 
15060 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {F12913} The pro
15070 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
15080 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
15090 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
150a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
150b0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
150c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
150d0 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  er()]..**.** {F1
150e0 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68  2914} The fourth
150f0 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74   argument [sqlit
15100 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
15110 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20  ler()] is a.*** 
15120 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69          void poi
15130 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
15140 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
15150 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
15160 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
15170 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
15180 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35  d..**.** {F12915
15190 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
151a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
151b0 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72  results in fewer
151c0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
151d0 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e    N opcodes bein
151e0 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20  g executed,.**  
151f0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
15200 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
15210 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
15220 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a  ked. {END}.** .*
15230 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79  * {F12916} Every
15240 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
15250 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
15260 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  er()].**        
15270 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79    overwrites any
15280 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
15290 73 74 65 72 65 20 70 72 6f 67 72 65 73 73 20 68  stere progress h
152a0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  andler..**.** {F
152b0 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72  12917} If the pr
152c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
152d0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20  allback is NULL 
152e0 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73  then no progress
152f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
15300 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e  dler is invoked.
15310 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20  .**.** {F12918} 
15320 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
15330 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15340 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20   a result other 
15350 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20  than 0, then.** 
15360 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68           the beh
15370 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73  avior is a if [s
15380 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15390 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c  ()] had been cal
153a0 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  led..*/.void sql
153b0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
153c0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
153d0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
153e0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
153f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
15400 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
15410 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
15420 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12700}.**.** Th
15430 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
15440 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
15450 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
15460 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e  name.** is given
15470 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   by the filename
15480 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
15490 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
154a0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
154b0 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66  ed as UTF-8.** f
154c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
154d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
154e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
154f0 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20  as UTF-16.** in 
15500 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
15510 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
15520 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
15530 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68   An [sqlite3*] h
15540 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
15550 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
15560 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61  Db, even.** if a
15570 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
15580 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
15590 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74 65  ion is if SQLite
155a0 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f   is unable.** to
155b0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
155c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
155d0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61  lite3] object, a
155e0 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65   NULL will.** be
155f0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
15600 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
15610 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
15620 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
15630 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  ..** If the data
15640 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
15650 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 0a  and/or created).
15660 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  ** successfully,
15670 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   then [SQLITE_OK
15680 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
15690 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a 20  Otherwise an.** 
156a0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
156b0 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  turned.  The.** 
156c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
156d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
156e0 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74  rrmsg16()]  rout
156f0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
15700 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
15710 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
15720 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
15730 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a   the error..**.*
15740 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e  * The default en
15750 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
15760 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
15770 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c  UTF-8 if.** [sql
15780 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
15790 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
157a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  ()] is called an
157b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
157c0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
157d0 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  rder if [sqlite3
157e0 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
157f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
15800 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
15810 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
15820 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
15830 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
15840 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71  ted with the [sq
15850 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73  lite3*] handle s
15860 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
15870 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a  d by passing it.
15880 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
15890 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
158a0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
158b0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
158c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
158d0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  2()] interface w
158e0 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  orks like [sqlit
158f0 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65  e3_open()] .** e
15900 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
15910 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
15920 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
15930 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
15940 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
15950 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
15960 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
15970 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
15980 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20  r can be.** one 
15990 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  of:.**.** <ol>.*
159a0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
159b0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a  OPEN_READONLY].*
159c0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
159d0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a  OPEN_READWRITE].
159e0 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
159f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
15a00 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
15a10 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e  CREATE].** </ol>
15a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
15a30 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65   value opens the
15a40 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f   database read-o
15a50 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20  nly. .** If the 
15a60 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
15a70 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69  t previously exi
15a80 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
15a90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
15aa0 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f   second option o
15ab0 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  pens.** the data
15ac0 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
15ad0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
15ae0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
15af0 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20  ding only if.** 
15b00 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
15b10 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20  rite protected. 
15b20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65 20   In either case 
15b30 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
15b40 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
15b50 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69  st or an error i
15b60 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
15b70 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a   third option.**
15b80 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
15b90 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
15ba0 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20  and writing and 
15bb0 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74  creates it if it
15bc0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72   does.** not alr
15bd0 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54  eady exist..** T
15be0 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73  he third options
15bf0 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61   is behavior tha
15c00 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
15c10 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
15c20 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  en()].** and [sq
15c30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
15c40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
15c50 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
15c60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
15c70 29 5d 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  )] is not one of
15c80 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
15c90 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
15ca0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
15cb0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
15cc0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
15cd0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
15ce0 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72  ry:", then an pr
15cf0 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f  ivate.** in-memo
15d00 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
15d10 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
15d20 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
15d30 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
15d40 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
15d50 73 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  sh when the data
15d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15d70 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
15d80 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  re.** version of
15d90 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61   SQLite might ma
15da0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
15db0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
15dc0 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62  enames.** that b
15dd0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
15de0 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74  " character.  It
15df0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
15e00 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20  that .** when a 
15e10 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
15e20 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65  e really does be
15e30 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20  gin with.** ":" 
15e40 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20  that you prefix 
15e50 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
15e60 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b  h a pathname lik
15e70 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f  e "./" to.** avo
15e80 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
15e90 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
15ea0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
15eb0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
15ec0 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79  rivate temporary
15ed0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
15ee0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
15ef0 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
15f00 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
15f10 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
15f20 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
15f30 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
15f40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15f50 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
15f60 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
15f70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15f80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
15f90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
15fa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
15fb0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
15fc0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
15fd0 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
15fe0 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
15ff0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
16000 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
16010 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  se.  If the.** f
16020 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
16030 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
16040 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
16050 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
16060 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73  .** object is us
16070 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
16080 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65  e to windows use
16090 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
160a0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
160b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
160c0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69  ment.** of [sqli
160d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
160e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
160f0 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d  ()] must be UTF-
16100 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
16110 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
16120 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
16130 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
16140 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
16150 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
16160 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
16170 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
16180 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
16190 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  them into.** [sq
161a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
161b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
161c0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
161d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
161e0 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12701} The [sqli
161f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
16200 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
16210 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
16220 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
16230 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
16240 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20  create a new.** 
16250 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
16260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
16270 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
16280 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64  *          the d
16290 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76  atabase file giv
162a0 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73  en in their firs
162b0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
162c0 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20  ** {F12702} The 
162d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
162e0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
162f0 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20   as UTF-8.**    
16300 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74        for [sqlit
16310 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
16320 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16330 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  )] and as UTF-16
16340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
16350 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
16360 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
16370 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
16380 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73  .** {F12703} A s
16390 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
163a0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
163b0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
163c0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a  e3_open16()], .*
163d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
163e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
163f0 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74  ] writes a point
16400 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
16410 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
16420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e  e connection] in
16430 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20  to *ppDb..**.** 
16440 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71  {F12704} The [sq
16450 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
16460 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
16470 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
16480 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
16490 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
164a0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
164b0 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73  _OK] upon succes
164c0 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  s,.**          o
164d0 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
164e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
164f0 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
16500 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66  {F12706} The def
16510 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
16520 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
16530 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
16540 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
16550 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16560 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
16570 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20  n_v2()] will be 
16580 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
16590 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c  2707} The defaul
165a0 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
165b0 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
165c0 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
165d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
165e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
165f0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a  will be UTF-16..
16600 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54  **.** {F12709} T
16610 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
16620 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  (F,D)] interface
16630 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
16640 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
16650 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
16660 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74  ,D,G,0)] where t
16670 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69  he G parameter i
16680 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
16690 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
166a0 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50  RITE]|[SQLITE_OP
166b0 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a  EN_CREATE]..**.*
166c0 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68  * {F12711} If th
166d0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
166e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
166f0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
16700 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
16710 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
16720 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
16730 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64  ONLY] then the d
16740 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
16750 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  d.**          fo
16760 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a  r reading only..
16770 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49  **.** {F12712} I
16780 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
16790 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
167a0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
167b0 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
167c0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
167d0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
167e0 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20  READWRITE] then 
167f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
16800 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
16810 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77     reading and w
16820 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
16830 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69  le, or for readi
16840 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a  ng only if the.*
16850 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20  *          file 
16860 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
16870 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
16880 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a  ing system..**.*
16890 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68  * {F12713} If th
168a0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
168b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
168c0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74  2(F,D,G,V)] omit
168d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
168e0 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
168f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
16900 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
16910 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
16920 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
16930 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
16940 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
16950 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66  *.** {F12714} If
16960 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
16970 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
16980 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n(v2(F,D,G,V)] c
16990 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
169a0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
169b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
169c0 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
169d0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
169e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
169f0 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74  viously exist, t
16a00 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hen an attempt i
16a10 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65  s made to create
16a20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
16a30 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
16a40 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
16a50 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20  {F12717} If the 
16a60 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
16a70 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
16a80 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
16a90 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
16aa0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
16ab0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
16ac0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
16ad0 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a  n an private,.**
16ae0 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
16af0 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  ral, in-memory d
16b00 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
16b10 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
16b20 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20  ction..**       
16b30 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
16b40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
16b50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
16b60 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
16b70 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
16b80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
16b90 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
16ba0 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c  2719} If the fil
16bb0 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72  ename is NULL or
16bc0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
16bd0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
16be0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
16bf0 68 65 72 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b  hermeral on-disk
16c00 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
16c10 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20  e created..**   
16c20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
16c30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
16c40 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
16c50 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
16c60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
16c70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16c80 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
16c90 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64   {F12721} The [d
16ca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16cb0 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a  on] created by .
16cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16cd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
16ce0 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20  ,G,V)] will use 
16cf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
16d00 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
16d10 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20  ject identified 
16d20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74  by the V paramet
16d30 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  er, or.**       
16d40 20 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b     the default [
16d50 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
16d60 65 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55  ect is V is a NU
16d70 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
16d80 2a 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b  * {F12723} Two [
16d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16da0 69 6f 6e 20 7c 20 64 61 74 61 62 61 73 65 20 63  ion | database c
16db0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
16dc0 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
16dd0 63 61 63 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  cache.**        
16de0 20 20 69 66 20 62 6f 74 68 20 77 65 72 65 20 6f    if both were o
16df0 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
16e00 61 6d 65 20 56 46 53 0a 2a 2a 20 20 20 20 20 20  ame VFS.**      
16e10 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
16e20 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
16e30 5f 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20  _cache | shared 
16e40 63 61 63 68 65 20 6d 6f 64 65 20 77 61 73 20 65  cache mode was e
16e50 6e 61 62 6c 65 64 5d 20 61 6e 64 0a 2a 2a 20 20  nabled] and.**  
16e60 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20          if both 
16e70 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72  filenames compar
16e80 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65  e equal using me
16e90 6d 63 6d 70 28 29 0a 2a 2a 20 20 20 20 20 20 20  mcmp().**       
16ea0 20 20 20 61 66 74 65 72 20 68 61 76 69 6e 67 20     after having 
16eb0 62 65 65 6e 20 70 72 6f 63 65 73 73 65 64 20 62  been processed b
16ec0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
16ed0 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61  fs | xFullPathna
16ee0 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a  me] method of.**
16ef0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 56 46            the VF
16f00 53 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c  S..**.*/.int sql
16f10 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
16f20 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
16f30 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
16f40 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
16f50 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
16f60 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
16f70 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16f80 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
16f90 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
16fa0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
16fb0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
16fc0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
16fd0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
16fe0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
16ff0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
17000 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
17010 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
17020 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
17030 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
17040 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
17050 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
17060 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
17070 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
17080 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
17090 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
170a0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
170b0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
170c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
170d0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
170e0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
170f0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
17100 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
17110 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
17120 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d  essages {F12800}
17130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17140 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
17150 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
17160 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53  he numeric.** [S
17170 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
17180 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  t code] or [SQLI
17190 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
171a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
171b0 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  code].** for the
171c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
171d0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
171e0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
171f0 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74  d.** with [sqlit
17200 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e  e3] handle 'db'.
17210 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
17220 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
17230 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
17240 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
17250 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
17260 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
17270 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
17280 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
17290 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
172a0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
172b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
172c0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
172d0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
172e0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
172f0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
17300 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
17310 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
17320 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
17330 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
17340 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
17350 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
17360 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
17370 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
17380 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69  need to worry wi
17390 74 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  th freeing the r
173a0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
173b0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
173c0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
173d0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
173e0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
173f0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
17400 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
17410 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
17420 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
17430 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
17440 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
17450 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
17460 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
17470 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
17480 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
17490 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
174a0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
174b0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
174c0 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
174d0 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20  esult code].**  
174e0 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
174f0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61  most recently fa
17500 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
17510 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
17520 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
17530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17540 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
17550 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  F12803} The [sql
17560 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20  ite3_errmsg(D)] 
17570 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
17580 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20  msg16(D)].**    
17590 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
175a0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
175b0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68  language text th
175c0 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20  at describes.** 
175d0 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72           the err
175e0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79  or in the mostly
175f0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
17600 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c   interface call,
17610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
17620 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55  oded as either U
17630 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
17640 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
17650 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74   {F12807} The st
17660 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
17670 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
17680 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
17690 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
176a0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
176b0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
176c0 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  xt SQLite interf
176d0 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ace call..**.** 
176e0 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74  {F12808} Calls t
176f0 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
17700 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
17710 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a  n an error code.
17720 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61  **          (exa
17730 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
17740 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
17750 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
17760 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
17770 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67  r code or messag
17780 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
17790 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
177a0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
177b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
177c0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
177d0 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
177e0 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72  * {F12809} Inter
177f0 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
17800 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
17810 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
17820 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
17830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17840 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
17850 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17860 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
17870 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
17880 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
17890 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
178a0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
178b0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
178c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
178d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
178e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
178f0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
17900 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
17910 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
17920 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
17930 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
17940 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
17950 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
17960 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
17970 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
17980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17990 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
179a0 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a  bject {F13000}.*
179b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
179c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
179d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
179e0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
179f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
17a00 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
17a10 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  t single SQL sta
17a20 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a  tements.  This.*
17a30 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  * object is vari
17a40 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
17a50 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
17a60 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22  ment" or a .** "
17a70 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
17a80 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
17a90 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
17aa0 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c  t"..** .** The l
17ab0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
17ac0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
17ad0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
17ae0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
17af0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
17b00 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
17b10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17b20 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
17b30 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
17b40 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
17b50 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
17b60 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e   parameters usin
17b70 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  g.**      [sqlit
17b80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
17b90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e  qlite3_bind_* in
17ba0 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c  terfaces]..** <l
17bb0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
17bc0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
17bd0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
17be0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
17bf0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
17c00 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
17c10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
17c20 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
17c30 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
17c40 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
17c50 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
17c60 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
17c70 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
17c80 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17c90 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
17ca0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
17cb0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
17cc0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
17cd0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
17ce0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
17cf0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
17d00 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
17d10 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
17d20 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
17d30 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
17d40 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a  mits {F12760}.**
17d50 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
17d60 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
17d70 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
17d80 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
17d90 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
17da0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
17db0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
17dc0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
17dd0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
17de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17df0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
17e00 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
17e10 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
17e20 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17e30 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
17e40 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
17e50 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
17e60 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
17e70 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
17e80 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
17e90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17ea0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
17eb0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
17ec0 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75  nstruct.  The fu
17ed0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17ee0 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a  he old limit..**
17ef0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c  .** If the new l
17f00 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
17f10 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
17f20 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
17f30 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69  d..** For the li
17f40 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20  mit category of 
17f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a  SQLITE_LIMIT_XYZ
17f60 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64   there is a hard
17f70 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20   upper.** bound 
17f80 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
17f90 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 65  -time C-preproce
17fa0 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53  ss macro named S
17fb0 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a  QLITE_MAX_XYZ..*
17fc0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
17fd0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
17fe0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
17ff0 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73  _".).** Attempts
18000 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
18010 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
18020 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
18030 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
18040 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
18050 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69   hard upper limi
18060 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d  t..**.** Run tim
18070 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
18080 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
18090 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
180a0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
180b0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
180c0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
180d0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
180e0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
180f0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
18100 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
18110 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
18120 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
18130 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
18140 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
18150 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
18160 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
18170 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
18180 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
18190 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 6a   controlled by j
181a0 61 76 61 73 63 72 69 70 74 20 61 70 70 6c 69 63  avascript applic
181b0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
181c0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 69 6e 74  d.** off the int
181d0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
181e0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
181f0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
18200 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
18210 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
18220 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
18230 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
18240 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
18250 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
18260 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
18270 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
18280 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
18290 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f 70  attach.  Develop
182a0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
182b0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
182c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
182d0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
182e0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
182f0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
18300 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
18310 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
18320 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
18330 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
18340 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
18350 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
18360 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
18370 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
18380 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
18390 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ce is currently 
183a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
183b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
183c0 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61  ubject.** to cha
183d0 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77  nge or removal w
183e0 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74  ithout prior not
183f0 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ice..**.** INVAR
18400 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
18410 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66  2762} A successf
18420 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
18430 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
18440 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20  ] where V is.** 
18450 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76           positiv
18460 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
18470 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 20            limit 
18480 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
18490 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b 64  onstruct C in [d
184a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
184b0 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
184c0 20 20 74 6f 20 74 68 65 20 6c 65 73 73 6f 72 20    to the lessor 
184d0 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72  of V and the har
184e0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  d upper bound on
184f0 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20   the size.**    
18500 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 20        of C that 
18510 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  is set at compil
18520 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e-time..**.** {F
18530 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73  12766} A success
18540 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
18550 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
18560 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65  )] where V is ne
18570 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
18580 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74     leaves the st
18590 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73 65  ate of [database
185a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75   connection] D u
185b0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
185c0 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 65  {F12769} A succe
185d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
185e0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
185f0 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  ,V)] returns the
18600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
18610 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20  ue of the limit 
18620 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
18630 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a  onstruct C in.**
18640 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64 61            in [da
18650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18660 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70  n] D as it was p
18670 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
18680 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18690 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
186a0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
186b0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
186c0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
186d0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
186e0 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59   {F12790}.** KEY
186f0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
18700 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
18710 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a  ategories}.** .*
18720 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
18730 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
18740 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64   aspects of a [d
18750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18760 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  on].** that can 
18770 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69  be limited in si
18780 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b  ze by calls to [
18790 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
187a0 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67  ..** The meaning
187b0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
187c0 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66   limits are as f
187d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64  ollows:.**.** <d
187e0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
187f0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
18800 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
18810 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
18820 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 62  y.** string or b
18830 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  lob or table row
18840 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  .<dd>.**.** <dt>
18850 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
18860 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
18870 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18880 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
18890 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
188a0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
188b0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
188c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
188d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
188e0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
188f0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
18900 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
18910 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
18920 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  CT or the maximu
18930 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
18940 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
18950 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
18960 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
18970 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a   clause.</dd>.**
18980 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
18990 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
189a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
189b0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
189c0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
189d0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
189e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
189f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
18a00 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
18a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18a20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18a30 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
18a40 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
18a50 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
18a60 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
18a70 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
18a80 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
18a90 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
18aa0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
18ab0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
18ac0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
18ad0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
18ae0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  QL statement.</d
18af0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18b00 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
18b10 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
18b20 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18b30 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
18b40 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
18b50 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18b60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
18b70 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
18b80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18b90 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65  umber of attache
18ba0 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64  d databases.</dd
18bb0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18bc0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
18bd0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
18be0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
18bf0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
18c00 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
18c10 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20  ent to the LIKE 
18c20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61  or.** GLOB opera
18c30 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tors.</dd>.**.**
18c40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18c50 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
18c60 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
18c70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
18c80 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
18c90 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18ca0 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
18cb0 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20   bound.</dd>.** 
18cc0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18cd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
18ce0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
18cf0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
18d00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
18d10 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
18d20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
18d30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18d40 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
18d50 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
18d60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
18d70 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
18d80 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
18d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
18da0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
18db0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
18dc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
18dd0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
18de0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
18df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
18e00 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
18e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
18e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
18e30 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
18e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
18e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e60 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
18e70 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
18e80 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
18e90 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
18ea0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
18eb0 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   9../*.** CAPI3R
18ec0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
18ed0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
18ee0 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f  F13010}.**.** To
18ef0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
18f00 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
18f10 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
18f20 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
18f30 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
18f40 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
18f50 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a  routines. .**.**
18f60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18f70 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b  ent "db" is an [
18f80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18f90 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65  ion] .** obtaine
18fa0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63  d from a prior c
18fb0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
18fc0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
18fd0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20  3_open_v2()].** 
18fe0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
18ff0 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73  16()]. .** The s
19000 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22  econd argument "
19010 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74 61  zSql" is the sta
19020 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
19030 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
19040 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
19050 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
19060 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
19070 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
19080 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
19090 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73 20  interfaces uses 
190a0 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65  UTF-8 and sqlite
190b0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
190c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
190d0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
190e0 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a  UTF-16. {END}.**
190f0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
19100 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
19110 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20  s.** than zero, 
19120 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
19130 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  d up to the firs
19140 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
19150 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 69  r..** If nByte i
19160 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
19170 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
19180 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
19190 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20   .** bytes read 
191a0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
191b0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
191c0 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
191d0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
191e0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
191f0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
19200 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
19210 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74   or .** the nByt
19220 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
19230 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
19240 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
19250 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
19260 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
19270 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
19280 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
19290 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
192a0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
192b0 61 67 65 20 74 6f 20 62 65 20 68 61 64 20 62 79  age to be had by
192c0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
192d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
192e0 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f   .** is equal to
192f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
19300 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
19310 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
19320 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68  uding</i> .** th
19330 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
19340 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a   bytes.{END}.**.
19350 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  ** *pzTail is ma
19360 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
19370 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61  he first byte pa
19380 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
19390 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73  e.** first SQL s
193a0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
193b0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
193c0 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20  s only compiles 
193d0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61  the first.** sta
193e0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
193f0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
19400 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
19410 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75  hat remains.** u
19420 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
19430 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
19440 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
19450 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
19460 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19470 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
19480 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
19490 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
194a0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
194b0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
194c0 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c  s.** set to NULL
194d0 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
194e0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
194f0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
19500 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70  ut.** is and emp
19510 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
19520 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
19530 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
19540 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d  ULL..** {U13018}
19550 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
19560 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
19570 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
19580 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ng the.** compil
19590 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
195a0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
195b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
195c0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
195d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
195e0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
195f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
19600 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
19610 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  ise an .** [erro
19620 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
19630 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
19640 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19650 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
19660 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
19670 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
19680 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
19690 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
196a0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
196b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
196c0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
196d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
196e0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
196f0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
19700 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
19710 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
19720 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
19730 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
19740 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
19750 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
19760 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
19770 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19780 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
19790 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69   text. {END} Thi
197a0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
197b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
197c0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
197d0 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
197e0 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
197f0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
19800 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
19810 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
19820 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
19830 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
19840 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
19850 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
19860 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
19870 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
19880 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
19890 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
198a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
198b0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
198c0 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
198d0 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
198e0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
198f0 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
19900 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
19910 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
19920 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
19930 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19940 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
19950 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
19960 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20  y behavior, .** 
19970 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
19980 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  is now a fatal e
19990 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a  rror.  Calling.*
199a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
199b0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
199c0 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
199d0 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
199e0 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
199f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
19a00 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
19a10 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
19a20 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
19a30 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
19a40 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
19a50 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f  urn. {END}.** </
19a60 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
19a70 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
19a80 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c  occurs, .** [sql
19a90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
19aa0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
19ab0 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a  the detailed .**
19ac0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
19ad0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
19ae0 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68  r codes]. .** Th
19af0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
19b00 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69  r was that [sqli
19b10 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
19b20 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
19b30 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  generic.** [SQLI
19b40 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
19b50 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f   code and you wo
19b60 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
19b70 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
19b80 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
19b90 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  set()] in order 
19ba0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
19bb0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
19bc0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20  the problem..** 
19bd0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
19be0 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
19bf0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
19c00 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
19c10 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
19c20 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
19c30 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
19c40 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ol>.**.** INVARI
19c50 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
19c60 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
19c70 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
19c80 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
19c90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
19ca0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
19cb0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
19cc0 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
19cd0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
19ce0 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
19cf0 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
19d00 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  TF-8..**.** {F13
19d10 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  012} The [sqlite
19d20 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a  3_prepare16(db,z
19d30 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
19d40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
19d50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19d60 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
19d70 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
19d80 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
19d90 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
19da0 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
19db0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
19dc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19dd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  er..**.** {F1301
19de0 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
19df0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
19e00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19e10 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
19e20 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
19e30 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
19e40 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
19e50 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78  ro, then SQL tex
19e60 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
19e70 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
19e80 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
19e90 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
19ea0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
19eb0 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
19ec0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
19ed0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19ee0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
19ef0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
19f00 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
19f10 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
19f20 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
19f30 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
19f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
19f50 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
19f60 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
19f70 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  F13015} In [sqli
19f80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
19f90 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
19fa0 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
19fb0 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
19fc0 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
19fd0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
19fe0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
19ff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1a000 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
1a010 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
1a020 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1a030 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1a040 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
1a050 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
1a060 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1a070 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1a080 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
1a090 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1a0a0 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
1a0b0 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
1a0c0 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
1a0d0 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
1a0e0 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75  ** {F13016} A su
1a0f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1a100 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a110 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
1a120 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
1a130 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
1a140 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
1a150 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
1a160 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
1a170 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1a180 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1a190 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
1a1a0 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20  ter to NULL.**  
1a1b0 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20          if zSql 
1a1c0 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
1a1d0 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
1a1e0 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
1a1f0 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ts. .**.** {F130
1a200 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1a210 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1a220 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1a230 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1a240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1a250 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1a260 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1a270 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1a280 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
1a290 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1a2a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1a2b0 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1a2c0 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1a2d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1a2e0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1a2f0 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1a300 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1a310 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20  QLITE_OK]).**   
1a320 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20         it first 
1a330 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20  sets *ppStmt to 
1a340 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1a350 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
1a360 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1a370 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1a380 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1a390 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1a3a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1a3b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1a3c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1a3d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1a3e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1a3f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1a400 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1a410 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1a420 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1a430 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1a440 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a450 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1a460 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1a470 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1a480 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1a490 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1a4a0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1a4b0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1a4c0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1a4d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a4e0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1a4f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1a500 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1a510 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a520 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a530 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a540 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a550 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a560 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a570 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a580 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a590 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1a5a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a5b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a5c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a5d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1a5e0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1a5f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1a600 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1a610 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1a620 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1a630 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1a640 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1a650 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1a660 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1a670 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1a680 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1a690 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1a6a0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1a6b0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1a6c0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1a6d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1a6e0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1a6f0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1a700 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1a710 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1a720 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1a730 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1a740 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1a750 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1a760 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1a770 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1a780 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1a790 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1a7a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1a7b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1a7c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1a7d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1a7e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1a7f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1a800 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1a810 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1a820 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1a830 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1a840 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1a850 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1a860 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a  ../*.** CAPIREF:
1a870 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1a880 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30  ement SQL {F1310
1a890 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
1a8a0 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20  tereface can be 
1a8b0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1a8c0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1a8d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1a8e0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1a8f0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1a900 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1a910 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1a920 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31  S:.**.** {F13101
1a930 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1a940 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1a950 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1a960 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1a970 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1a980 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1a990 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1a9a0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1a9b0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1a9c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1a9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a9e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a9f0 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  v2()],.**       
1aa00 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
1aa10 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e  _sql()] function
1aa20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1aa30 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20  er to a.**      
1aa40 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1aa50 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  ted string conta
1aa60 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65  ining a UTF-8 re
1aa70 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ndering.**      
1aa80 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69      of the origi
1aa90 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  nal SQL statemen
1aaa0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32  t..**.** {F13102
1aab0 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1aac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1aad0 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1aae0 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1aaf0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1ab00 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1ab10 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1ab20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1ab30 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1ab40 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
1ab50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ab60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
1ab70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ab80 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1ab90 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1aba0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1abb0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33  r..**.** {F13103
1abc0 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1abd0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1abe0 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1abf0 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1ac00 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1ac10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1ac20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1ac30 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1ac40 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1ac50 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1ac60 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1ac70 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1ac80 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d  CAPI3REF:  Dynam
1ac90 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1aca0 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30  ue Object  {F150
1acb0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
1acc0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1acd0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1ace0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1acf0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1ad00 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1ad10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ad20 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1ad30 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1ad40 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1ad50 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1ad60 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ble..** SQLite u
1ad70 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1ad80 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ng for the value
1ad90 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a  s it stores.  .*
1ada0 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  * Values stored 
1adb0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1adc0 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a   objects can be.
1add0 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  ** be integers, 
1ade0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1adf0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1ae00 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1ae10 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1ae20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1ae30 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1ae40 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1ae50 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1ae60 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1ae70 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1ae80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1ae90 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1aea0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1aeb0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1aec0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1aed0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1aee0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1aef0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1af00 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1af10 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1af20 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68  cifies .** wheth
1af30 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1af40 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1af50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1af60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1af70 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1af80 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1af90 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1afa0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1afb0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1afc0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1afd0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1afe0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1aff0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1b000 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1b010 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1b020 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1b030 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1b040 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1b050 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1b060 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1b070 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ith SQLITE_THREA
1b080 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68  DSAFE=0 and with
1b090 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1b0a0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1b0b0 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  g 0).** then the
1b0c0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1b0d0 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
1b0e0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1b0f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1b100 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1b110 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a  and they can be.
1b120 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  ** used intercha
1b130 6e 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72  ngable.  However
1b140 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  , for maximum co
1b150 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1b160 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e  t.** is recommen
1b170 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1b180 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64  tions make the d
1b190 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1b1a0 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72  en.** between pr
1b1b0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1b1c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1b1d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
1b1e0 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72  en if.** they ar
1b1f0 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65  e single threade
1b200 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1b210 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1b220 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1b230 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1b240 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1b250 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
1b260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1b270 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1b280 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1b290 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
1b2a0 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
1b2b0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
1b2c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
1b2d0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
1b2e0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
1b2f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1b300 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
1b310 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
1b320 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
1b330 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
1b340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
1b350 75 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 65  ue()].  All othe
1b360 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
1b370 74 68 61 74 20 75 73 65 20 73 71 6c 69 74 65 33  that use sqlite3
1b380 5f 76 61 6c 75 65 20 72 65 71 75 69 72 65 20 70  _value require p
1b390 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1b3a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1b3b0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1b3c0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1b3d0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1b3e0 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74  3REF:  SQL Funct
1b3f0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
1b400 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a  ct {F16001}.**.*
1b410 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1b420 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1b430 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1b440 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1b450 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1b460 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f  xt object.  A po
1b470 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
1b480 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f  te3_context.** o
1b490 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20  bject is always 
1b4a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b4b0 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  to application-d
1b4c0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1b4d0 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ions..*/.typedef
1b4e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1b4f0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1b500 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1b510 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
1b520 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1b530 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1b540 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13500}.**.** 
1b550 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1b560 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1b570 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b580 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61  )] and its.** va
1b590 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73  riants, literals
1b5a0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20   may be replace 
1b5b0 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
1b5c0 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73  n one.** of thes
1b5d0 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1b5e0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1b5f0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1b600 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1b610 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1b620 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1b630 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1b640 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1b650 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1b660 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1b670 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61  al,.** VVV alpha
1b680 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1b690 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  er name..** The 
1b6a0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20  values of these 
1b6b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1b6c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1b6d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a  rameter names".*
1b6e0 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  * or "SQL parame
1b6f0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1b700 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1b710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1b720 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1b730 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
1b740 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1b750 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1b760 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1b770 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20   always.** is a 
1b780 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1b790 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1b7a0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1b7b0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1b7c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b7d0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68  its variants. Th
1b7e0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
1b7f0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1b800 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  x of the paramet
1b810 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68  er to be set. Th
1b820 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
1b830 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1b840 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1b850 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1b860 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
1b870 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
1b880 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
1b890 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
1b8a0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
1b8b0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
1b8c0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1b8d0 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65  ce. .** The inde
1b8e0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
1b8f0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
1b900 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
1b910 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
1b920 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1b930 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  e()] API if desi
1b940 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
1b950 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1b960 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1b970 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1b980 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
1b990 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1b9a0 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
1b9b0 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
1b9c0 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
1b9d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
1b9e0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1b9f0 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
1ba00 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
1ba10 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
1ba20 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
1ba30 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
1ba40 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
1ba50 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1ba60 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1ba70 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
1ba80 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1ba90 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1baa0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1bab0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1bac0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1bad0 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68  tes</u>.** in th
1bae0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1baf0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1bb00 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68  cters. .** If th
1bb10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1bb20 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1bb30 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1bb40 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e  e string is.** n
1bb50 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1bb60 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1bb70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1bb80 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
1bb90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1bba0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
1bbb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1bbc0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
1bbd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1bbe0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
1bbf0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
1bc00 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
1bc10 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
1bc20 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
1bc30 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49  ished with it. I
1bc40 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1bc50 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1bc60 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1bc70 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1bc80 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1bc90 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1bca0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1bcb0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1bcc0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1bcd0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1bce0 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  freed..** If the
1bcf0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1bd00 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1bd10 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1bd20 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1bd30 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1bd40 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1bd50 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1bd60 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1bd70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1bd80 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1bd90 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
1bda0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1bdb0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1bdc0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1bdd0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1bde0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1bdf0 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  eros.  A zeroblo
1be00 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1be10 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1be20 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1be30 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73  ger to hold it s
1be40 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1be50 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1be60 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1be70 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1be80 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f  erve as place-ho
1be90 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1bea0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1beb0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1bec0 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
1bed0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1bee0 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
1bef0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
1bf00 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
1bf10 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1bf20 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1bf30 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1bf40 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1bf50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1bf60 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1bf70 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1bf80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1bf90 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1bfa0 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1bfb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1bfc0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1bfd0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1bfe0 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1bff0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1c000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1c010 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1c020 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1c030 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1c040 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1c050 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c060 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1c070 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1c080 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1c090 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1c0a0 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1c0b0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1c0c0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1c0d0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1c0e0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1c0f0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1c100 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1c110 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a  malloc fails..**
1c120 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
1c130 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
1c140 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
1c150 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1c160 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
1c170 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
1c180 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
1c190 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
1c1a0 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
1c1b0 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
1c1c0 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
1c1d0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
1c1e0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1c1f0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
1c200 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
1c210 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
1c220 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
1c230 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
1c240 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
1c250 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
1c260 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
1c270 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1c280 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
1c290 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
1c2a0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
1c2b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1c2c0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1c2d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1c2e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1c2f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1c300 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1c310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1c320 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1c330 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1c340 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36  S:.**.** {F13506
1c350 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1c360 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61  repare | SQL sta
1c370 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
1c380 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20   recognizes.**  
1c390 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f          tokens o
1c3a0 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c  f the forms "?",
1c3b0 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
1c3c0 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
1c3d0 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  VV".**          
1c3e0 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
1c3f0 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20  s, where NNN is 
1c400 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1c410 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
1c420 20 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61          digits a
1c430 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
1c440 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
1c450 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20  one or more .** 
1c460 20 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75           alphanu
1c470 6d 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73  meric characters
1c480 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
1c490 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a  lly followed by.
1c4a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74  **          a st
1c4b0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1c4c0 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
1c4d0 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
1c4e0 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
1c4f0 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69  * {F13509} The i
1c500 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
1c510 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1c520 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1c530 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {F13512} The ind
1c540 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
1c550 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1c560 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1c570 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
1c580 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
1c590 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
1c5a0 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
1c5b0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1c5c0 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
1c5d0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1c5e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ter..**.** {F135
1c5f0 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
1c600 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
1c610 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1c620 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
1c630 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20  ** {F13518} The 
1c640 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
1c650 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
1c660 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
1c670 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
1c680 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
1c690 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
1c6a0 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 20  most occurances 
1c6b0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
1c6c0 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
1c6d0 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
1c6e0 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
1c6f0 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
1c700 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1c710 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
1c720 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
1c730 20 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e 63   first occurranc
1c740 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1c750 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
1c760 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
1c770 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
1c780 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1c790 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13521} The [sql
1c7a0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1c7b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1c7c0 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68  piler] fail with
1c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
1c7e0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65  [SQLITE_RANGE] e
1c7f0 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
1c800 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1c810 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
1c820 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31    is less than 1
1c830 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1c840 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1c850 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a  ABLE_NUMBER..**.
1c860 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c  ** {F13524} Call
1c870 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c880 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c890 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
1c8a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1c8b0 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
1c8c0 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
1c8d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
1c8e0 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
1c8f0 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
1c900 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1c910 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
1c920 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c  ** {F13527} Call
1c930 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c940 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1c950 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
1c960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1c970 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
1c980 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
1c990 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
1c9a0 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  N..**.** {F13530
1c9b0 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
1c9c0 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
1c9d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c9e0 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
1c9f0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1ca00 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
1ca10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ca20 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
1ca30 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61  * {F13533} In ca
1ca40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1ca50 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1ca60 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1ca70 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1ca80 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1ca90 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1caa0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1cab0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1cac0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1cad0 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
1cae0 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
1caf0 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
1cb00 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1cb10 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
1cb20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
1cb30 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1cb40 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  F13536} In calls
1cb50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1cb60 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1cb70 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1cb80 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1cb90 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1cba0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1cbb0 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
1cbc0 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
1cbd0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
1cbe0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
1cbf0 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
1cc00 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39  e..**.** {F13539
1cc10 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1cc20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1cc30 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1cc40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1cc50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1cc60 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1cc70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1cc80 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1cc90 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1cca0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
1ccb0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
1ccc0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
1ccd0 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
1cce0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
1ccf0 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
1cd00 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
1cd10 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
1cd20 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
1cd30 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
1cd40 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
1cd50 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1cd60 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
1cd70 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  F13542} In calls
1cd80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1cd90 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1cda0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1cdb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1cdc0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1cdd0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1cde0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1cdf0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1ce00 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1ce10 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1ce20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1ce30 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1ce40 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
1ce50 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   a .**          
1ce60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1ce70 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69  V value before i
1ce80 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
1ce90 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
1cea0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1ceb0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1cec0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1ced0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1cee0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1cef0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1cf00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1cf10 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1cf20 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
1cf30 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
1cf40 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
1cf50 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
1cf60 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
1cf70 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
1cf80 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65           V value
1cf90 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1cfa0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
1cfb0 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20   V value..**.** 
1cfc0 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
1cfd0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1cfe0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
1cff0 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
1d000 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
1d010 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c    is a blob of L
1d020 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
1d030 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66  o-length blob if
1d040 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
1d050 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49  **.** {F13551} I
1d060 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1d070 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
1d080 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
1d090 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
1d0a0 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
1d0b0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
1d0c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1d0d0 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
1d0e0 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
1d0f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1d100 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
1d110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d120 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1d130 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1d140 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1d150 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1d160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1d170 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1d180 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1d190 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1d1a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1d1b0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1d1c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1d1d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1d1e0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1d1f0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1d200 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1d210 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1d220 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1d230 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1d240 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1d250 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1d260 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1d270 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1d280 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1d290 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1d2a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1d2b0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1d2c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1d2d0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1d2e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1d2f0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1d300 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1d310 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1d320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d330 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1d340 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1d350 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1d360 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
1d370 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1d380 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1d390 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1d3a0 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1d3b0 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72  s.** in a prepar
1d3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ed statement.  S
1d3d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1d3e0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1d3f0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1d400 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1d410 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1d420 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1d430 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1d440 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1d450 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1d460 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1d470 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1d480 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1d490 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
1d4a0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
1d4b0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
1d4c0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
1d4d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46   parameter..** F
1d4e0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1d4f0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1d500 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1d510 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  o the number of.
1d520 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  ** unique parame
1d530 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1d540 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1d550 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65   are used, there
1d560 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20   may.** be gaps 
1d570 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1d580 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1d590 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1d5a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1d5b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d5c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1d5d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1d5e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1d5f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1d600 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1d610 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54  **.** {F13601} T
1d620 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1d630 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1d640 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
1d650 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1d660 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69     the largest i
1d670 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20  ndex of all SQL 
1d680 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68  parameters in th
1d690 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1d6a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d6b0 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a  t] S, or 0 if S.
1d6c0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
1d6d0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
1d6e0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
1d6f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d700 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1d710 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1d720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1d730 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1d740 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a  meter {F13620}.*
1d750 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1d760 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1d770 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
1d780 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53  of the n-th.** S
1d790 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
1d7a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1d7b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1d7c0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1d7d0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1d7e0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1d7f0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1d800 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1d810 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1d820 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1d830 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1d840 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1d850 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1d860 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1d870 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1d880 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1d890 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1d8a0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
1d8b0 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
1d8c0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1d8d0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1d8e0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1d8f0 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  o name..**.** Th
1d900 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
1d910 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1d920 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
1d930 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
1d940 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
1d950 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
1d960 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
1d970 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
1d980 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
1d990 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
1d9a0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
1d9b0 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20 55   always in the U
1d9c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
1d9d0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
1d9e0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
1d9f0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
1da00 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
1da10 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
1da20 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
1da30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1da40 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1da50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1da60 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1da70 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1da80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1da90 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1daa0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1dab0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1dac0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1dad0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1dae0 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20  ** {F13621} The 
1daf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1db00 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e  rameter_name(S,N
1db10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1db20 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
1db30 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1db40 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f  ng of the name o
1db50 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
1db60 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ter in.**       
1db70 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1db80 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67  tement] S having
1db90 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20   index N, or.** 
1dba0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66           NULL if
1dbb0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c   there is no SQL
1dbc0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
1dbd0 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68  index N or if th
1dbe0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
1dbf0 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
1dc00 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79  ex N is an anony
1dc10 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22  mous parameter "
1dc20 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ?"..*/.const cha
1dc30 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1dc40 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1dc50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1dc60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1dc70 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1dc80 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1dc90 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33   Given Name {F13
1dca0 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  640}.**.** Retur
1dcb0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
1dcc0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1dcd0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
1dce0 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
1dcf0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
1dd00 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
1dd10 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
1dd20 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
1dd30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1dd40 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1dd50 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
1dd60 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
1dd70 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
1dd80 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
1dd90 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1dda0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1ddb0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1ddc0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1ddd0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1dde0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1ddf0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1de00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1de10 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1de20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1de30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1de40 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1de50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1de60 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1de70 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1de80 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1de90 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1dea0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1deb0 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68  *.** {F13641} Th
1dec0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1ded0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1dee0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
1def0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
1df00 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66      the index of
1df10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1df20 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
1df30 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
1df40 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20     S whose name 
1df50 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d  matches the UTF-
1df60 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30  8 string N, or 0
1df70 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20   if there is.** 
1df80 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63           no matc
1df90 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  h..*/.int sqlite
1dfa0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1dfb0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
1dfc0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
1dfd0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
1dfe0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
1dff0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
1e000 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
1e010 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a  ement {F13660}.*
1e020 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f  *.** Contrary to
1e030 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
1e040 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
1e050 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
1e060 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20  ot.** reset the 
1e070 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1e080 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
1e090 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  n a .** [prepare
1e0a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55  d statement].  U
1e0b0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
1e0c0 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20  to.** reset all 
1e0d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
1e0e0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
1e0f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1e100 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {F13661} The [s
1e110 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
1e120 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
1e130 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a  ace resets all.*
1e140 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70  *          SQL p
1e150 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1e160 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73  s in [prepared s
1e170 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
1e180 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
1e190 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1e1a0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
1e1b0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
1e1c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1e1d0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
1e1e0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
1e1f0 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a  lt Set {F13710}.
1e200 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
1e210 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1e220 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
1e230 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
1e240 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
1e250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
1e260 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
1e270 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d  rns 0.** if pStm
1e280 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74  t is an SQL stat
1e290 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
1e2a0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
1e2b0 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65  (for .** example
1e2c0 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a   an UPDATE)..**.
1e2d0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1e2e0 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68  *.** {F13711} Th
1e2f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1e300 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  n_count(S)] inte
1e310 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1e320 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
1e330 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20          columns 
1e340 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
1e350 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74  t generated by t
1e360 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1e370 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e380 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53  nt] S, or 0 if S
1e390 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61   does not genera
1e3a0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
1e3b0 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a   result set..*/.
1e3c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1e3d0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
1e3e0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1e3f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e400 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
1e410 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31  A Result Set {F1
1e420 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3720}.**.** Thes
1e430 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1e440 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
1e450 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
1e460 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
1e470 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e480 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
1e490 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
1e4a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e4b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
1e4c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1e4d0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
1e4e0 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e  nated UTF8 strin
1e4f0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
1e500 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1e510 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1e520 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1e530 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36  minated.** UTF16
1e540 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
1e550 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1e560 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1e570 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1e580 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
1e590 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1e5a0 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  t..** The second
1e5b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1e5c0 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  e column number.
1e5d0 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20    The left-most 
1e5e0 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d  column is.** num
1e5f0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 0..**.** The
1e600 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1e610 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
1e620 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
1e630 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
1e640 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
1e650 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
1e660 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1e670 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
1e680 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74   next call sqlit
1e690 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1e6a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1e6b0 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f  mn_name16().** o
1e6c0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
1e6d0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69  n..**.** If sqli
1e6e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
1e6f0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
1e700 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
1e710 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
1e720 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
1e730 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
1e740 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
1e750 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
1e760 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
1e770 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
1e780 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
1e790 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
1e7a0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
1e7b0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
1e7c0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
1e7d0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
1e7e0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
1e7f0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
1e800 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
1e810 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
1e820 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
1e830 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
1e840 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
1e850 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
1e860 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
1e870 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1e880 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75  ** {F13721} A su
1e890 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1e8a0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
1e8b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e8c0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
1e8d0 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
1e8e0 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  rns the name.** 
1e8f0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1e900 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
1e910 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d  e 0 is the left-
1e920 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
1e930 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e940 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
1e950 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e960 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20  nt] S as a.**   
1e970 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1e980 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1e990 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ing..**.** {F137
1e9a0 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  23} A successful
1e9b0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
1e9c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1e9d0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a  mn_name16(S,N)].
1e9e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1e9f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ea00 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ea10 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f     of the Nth co
1ea20 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
1ea30 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   the left-most c
1ea40 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a  olumn) for the.*
1ea50 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
1ea60 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
1ea70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1ea80 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  as a.**         
1ea90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1eaa0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1eab0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1eac0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
1ead0 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c  F13724} The [sql
1eae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1eaf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1eb00 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
1eb10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
1eb20 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1eb30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
1eb40 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c  f they are unabl
1eb50 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  e to.**         
1eb60 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1eb70 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1eb80 74 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74  there normal ret
1eb90 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
1eba0 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74  ** {F13725} If t
1ebb0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1ebc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
1ebd0 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
1ebe0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1ebf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1ec00 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
1ec10 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
1ec20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
1ec30 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1ec40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1ec50 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36  ..** .** {F13726
1ec60 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
1ec70 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1ec80 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1ec90 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ,N)] and.**     
1eca0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1ecb0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
1ecc0 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  ] are valid unti
1ecd0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20  l the next.**   
1ece0 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65         call to e
1ecf0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69  ither routine wi
1ed00 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e  th the same S an
1ed10 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  d N parameters.*
1ed20 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
1ed30 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  til [sqlite3_fin
1ed40 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
1ed50 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  led..**.** {F137
1ed60 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c  27} When a resul
1ed70 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53  t column of a [S
1ed80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1ed90 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
1eda0 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75        an AS clau
1edb0 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  se, the name of 
1edc0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  that column is t
1edd0 68 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a  he indentifier.*
1ede0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
1edf0 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41  e right of the A
1ee00 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f  S keyword..*/.co
1ee10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1ee20 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
1ee30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ee40 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
1ee50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1ee60 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1ee70 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
1ee80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1ee90 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
1eea0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1eeb0 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13740}.**.** T
1eec0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
1eed0 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
1eee0 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
1eef0 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
1ef00 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
1ef10 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
1ef20 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  lt of a SELECT s
1ef30 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
1ef40 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  rom..** The name
1ef50 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1ef60 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
1ef70 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
1ef80 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
1ef90 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36   a UTF8 or UTF16
1efa0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
1efb0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
1efc0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
1efd0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
1efe0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
1eff0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
1f000 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
1f010 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
1f020 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
1f030 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
1f040 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1f050 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
1f060 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65  ntil.** the [pre
1f070 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f080 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73   is destroyed us
1f090 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1f0a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
1f0b0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
1f0c0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
1f0d0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
1f0e0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
1f0f0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
1f100 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
1f110 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
1f120 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
1f130 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
1f140 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
1f150 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
1f160 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1f170 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
1f180 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
1f190 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f1a0 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
1f1b0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
1f1c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
1f1d0 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
1f1e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1f1f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
1f200 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1f210 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
1f220 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
1f230 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1f240 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1f250 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
1f260 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f   expression.** o
1f270 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  r subquery and i
1f280 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
1f290 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
1f2a0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
1f2b0 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c  s.** return NULL
1f2c0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1f2d0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
1f2e0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
1f2f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
1f300 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1f310 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
1f320 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20   return the .** 
1f330 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
1f340 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
1f350 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1f360 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
1f370 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20  t.** column was 
1f380 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
1f390 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c  **.** As with al
1f3a0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
1f3b0 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66  PIs, those postf
1f3c0 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72  ixed with "16" r
1f3d0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
1f3e0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c  encoded strings,
1f3f0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
1f400 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
1f410 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  8. {END}.**.** T
1f420 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
1f430 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
1f440 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
1f450 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1f460 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  e .** SQLITE_ENA
1f470 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
1f480 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
1f490 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
1f4a0 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a  .**.** {U13751}.
1f4b0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
1f4c0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
1f4d0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
1f4e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
1f4f0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
1f500 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f510 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
1f520 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1f530 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1f540 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
1f550 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
1f560 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1f570 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
1f580 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
1f590 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
1f5a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1f5b0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1f5c0 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
1f5d0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1f5e0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1f5f0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f600 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f610 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f630 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f640 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f650 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f660 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f670 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f680 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f690 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f6a0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f6b0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f6c0 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f6d0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f6e0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32       .** {F13742
1f6f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1f700 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1f710 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
1f720 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1f730 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1f740 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
1f750 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
1f760 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
1f770 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1f780 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1f790 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f7a0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f7b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f7c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f7d0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f7e0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f7f0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f800 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f810 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f820 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f830 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f840 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f850 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f860 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f870 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f880 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d      .** {F13743}
1f890 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f8a0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
1f8b0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
1f8c0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
1f8d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
1f8e0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1f8f0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
1f900 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63   table from whic
1f910 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1f920 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1f930 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1f940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1f950 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1f960 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1f970 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1f980 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1f990 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1f9a0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1f9b0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1f9c0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1f9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1f9e0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1f9f0 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1fa00 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {F13744} The [sq
1fa10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1fa20 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
1fa30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1fa40 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1fa50 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
1fa60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1fa70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
1fa80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
1fa90 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
1faa0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1fab0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1fac0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1fad0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fae0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1faf0 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1fb00 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1fb10 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1fb20 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1fb30 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1fb40 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1fb50 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1fb60 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1fb70 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1fb80 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1fb90 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35       .** {F13745
1fba0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1fbb0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1fbc0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
1fbd0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
1fbe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1fbf0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1fc00 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1fc10 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1fc20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1fc30 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1fc40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1fc50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fc60 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1fc70 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1fc80 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1fc90 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1fca0 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1fcb0 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1fcc0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1fcd0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1fce0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1fcf0 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1fd00 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1fd10 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36       .** {F13746
1fd20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1fd30 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1fd40 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
1fd50 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
1fd60 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
1fd70 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
1fd80 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
1fd90 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
1fda0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
1fdb0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1fdc0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
1fdd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
1fde0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1fdf0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1fe00 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
1fe10 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
1fe20 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
1fe30 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  he the Nth colum
1fe40 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1fe50 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1fe60 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1fe70 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1fe80 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1fe90 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1fea0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1feb0 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1fec0 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  8} The return va
1fed0 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  lues from.**    
1fee0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
1fef0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1ff00 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  ame|column metad
1ff10 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
1ff20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
1ff30 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20  valid.**        
1ff40 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69    for the lifeti
1ff50 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  me of the [prepa
1ff60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1ff70 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
1ff80 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  til the encoding
1ff90 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61   is changed by a
1ffa0 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a  nother metadata.
1ffb0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1ffc0 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74  rface call for t
1ffd0 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64  he same prepared
1ffe0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
1fff0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  olumn..**.** LIM
20000 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
20010 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20  {U13751} If two 
20020 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
20030 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
20040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
20050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
20060 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d  abase_name|colum
20070 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
20080 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20  faces].**       
20090 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65     the same [pre
200a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
200b0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
200c0 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  mn.**          a
200d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
200e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
200f0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20100 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
20120 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
20130 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20140 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20160 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
20170 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20180 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20190 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
201a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
201b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
201c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
201d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
201e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
201f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20210 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
20220 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20230 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
20250 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
20260 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
20280 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
20290 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
202a0 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a  t {F13760}.**.**
202b0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
202c0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
202d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
202e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
202f0 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43  ement is a SELEC
20300 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  T statement and 
20310 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
20320 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e  f the .** return
20330 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
20340 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
20350 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
20360 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
20370 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
20380 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
20390 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
203a0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
203b0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66  is returned.  If
203c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
203d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
203e0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
203f0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
20400 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
20410 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
20420 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  ed..** The retur
20430 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
20440 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
20450 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46  ed.  {END} .** F
20460 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74  or example, in t
20470 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
20480 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
20490 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
204a0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64  IANT);.**.** And
204b0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
204c0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
204d0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
204e0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
204f0 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74  t1;.**.** Then t
20500 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
20510 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
20520 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
20530 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  r the second.** 
20540 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
20550 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
20560 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
20570 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
20580 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a  lumn.** (i==0)..
20590 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
205a0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
205b0 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a  me typing.  So j
205c0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
205d0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
205e0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
205f0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
20600 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
20610 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
20620 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
20630 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
20640 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
20650 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
20660 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
20670 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
20680 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
20690 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61  c.  Type.** is a
206a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
206b0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
206c0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
206d0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
206e0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
206f0 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  values..**.** IN
20700 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
20710 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63  {F13761}  A succ
20720 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
20730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20740 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a  ecltype(S,N)].**
20750 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
20760 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
20770 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
20780 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
20790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
207a0 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
207b0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
207c0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
207d0 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
207e0 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
207f0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
20800 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
20810 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
20820 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
20830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20840 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36   S..**.** {F1376
20850 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  2}  A successful
20860 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20870 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
20880 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
20890 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
208a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
208b0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
208c0 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
208d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
208e0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
208f0 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f  lared datatype o
20900 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
20910 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a  mn that appears.
20920 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
20930 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
20940 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29  numbered from 0)
20950 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
20960 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  et to the.**    
20970 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
20980 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
20990 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49  *.** {F13763}  I
209a0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
209b0 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74   0 or N is great
209c0 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  er than or equal
209d0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
209e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
209f0 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61  olumns in [prepa
20a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
20a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
20a20 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
20a30 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78  mn of S is an ex
20a40 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
20a50 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20  uery rather.**  
20a60 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20           than a 
20a70 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20  table column or 
20a80 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
20a90 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a  cation failure.*
20aa0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
20ab0 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69  rs during encodi
20ac0 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20  ng conversions, 
20ad0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
20ae0 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69    calls to [sqli
20af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
20b00 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  ype(S,N)] or.** 
20b10 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20b20 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20b30 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72  pe16(S,N)] retur
20b40 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74  n NULL..*/.const
20b50 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
20b60 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
20b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
20b80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
20b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20ba0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
20bb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
20bc0 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20   .** CAPI3REF:  
20bd0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
20be0 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30  Statement {F1320
20bf0 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0}.**.** After a
20c00 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
20c10 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
20c20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20  prepared with a 
20c30 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65  call.** to eithe
20c40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
20c50 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
20c60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20c70 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f  2()] or to one o
20c80 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20  f.** the legacy 
20c90 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
20ca0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
20cb0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
20cc0 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  re16()],.** then
20cd0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   this function m
20ce0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
20cf0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
20d00 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
20d10 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  .** statement..*
20d20 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
20d30 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
20d40 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33   of this sqlite3
20d50 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
20d60 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
20d70 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
20d80 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
20d90 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
20da0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
20db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20dc0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20dd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20de0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
20df0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
20e00 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
20e10 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
20e20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20e30 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
20e40 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
20e50 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
20e60 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
20e70 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
20e80 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
20e90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
20ea0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
20eb0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
20ec0 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
20ed0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
20ee0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
20ef0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
20f00 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b  ITE_BUSY], .** [
20f10 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
20f20 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
20f30 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
20f40 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
20f50 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22  ** With the "v2"
20f60 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
20f70 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51  of the other [SQ
20f80 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
20f90 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51   code].** or [SQ
20fa0 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
20fb0 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
20fc0 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65  t code] might be
20fd0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
20fe0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
20ff0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
21000 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
21010 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
21020 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
21030 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
21040 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
21050 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
21060 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21070 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72  s a COMMIT.** or
21080 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
21090 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
210a0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
210b0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
210c0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
210d0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
210e0 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d  nt is not a COMM
210f0 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  IT and occurs wi
21100 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
21110 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
21120 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
21130 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
21140 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
21150 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
21160 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
21170 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
21180 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
21190 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
211a0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
211b0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
211c0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
211d0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
211e0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
211f0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
21200 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
21210 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21220 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
21230 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
21240 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
21250 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
21260 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
21270 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
21280 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
21290 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a  y data, then .**
212a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73   [SQLITE_ROW] is
212b0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
212c0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
212d0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a   data is ready.*
212e0 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  * for processing
212f0 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   by the caller. 
21300 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
21310 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
21320 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
21330 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f  _column_int | co
21340 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
21350 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
21360 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
21370 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
21380 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
21390 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a  ow of data..** .
213a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
213b0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
213c0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
213d0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
213e0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
213f0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
21400 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21410 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
21420 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
21430 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
21440 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
21450 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
21460 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
21470 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  g()]..** With th
21480 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
21490 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
214a0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
214b0 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c  example:.** [SQL
214c0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
214d0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
214e0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
214f0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
21500 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
21510 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
21520 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21530 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
21540 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21550 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
21560 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
21570 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
21580 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
21590 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
215a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
215b0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
215c0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
215d0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
215e0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
215f0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
21600 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
21610 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
21620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21630 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
21640 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
21650 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
21660 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
21670 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a  one that had .**
21680 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
21690 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
216a0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
216b0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
216c0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
216d0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
216e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
216f0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
21700 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
21710 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
21720 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
21730 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n time..**.** <b
21740 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
21750 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49   Alert:</b>.** I
21760 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
21770 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20  erface, .** the 
21780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41  sqlite3_step() A
21790 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
217a0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
217b0 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49  r code,.** [SQLI
217c0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
217d0 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f  wing any error o
217e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
217f0 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b  E_BUSY].** and [
21800 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
21810 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b   You must call [
21820 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21830 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
21840 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
21850 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
21860 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63   of the specific
21870 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
21880 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
21890 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
218a0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
218b0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
218c0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
218d0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
218e0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
218f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21900 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
21910 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
21920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21930 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
21940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21950 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
21960 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21970 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
21980 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
21990 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
219a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
219b0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74  are16()], then t
219c0 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63  he .** more spec
219d0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
219e0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
219f0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
21a00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
21a10 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
21a20 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
21a30 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
21a40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21a50 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20  **.** {F13202}  
21a60 49 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  If [prepared sta
21a70 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61  tement] S is rea
21a80 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20  dy to be.**     
21a90 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20        run, then 
21aa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
21ab0 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20  ] advances that 
21ac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21ad0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nt.**           
21ae0 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74  until to complet
21af0 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20  ion or until it 
21b00 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  is ready to retu
21b10 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20  rn another.**   
21b20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74          row of t
21b30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72  he result set or
21b40 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72   an interrupt or
21b50 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
21b60 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  occurs..**.** {F
21b70 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63  15304}  When a c
21b80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21b90 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20  step(S)] causes 
21ba0 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
21bb0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
21bc0 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20  ement] S to run 
21bd0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a  to completion,.*
21be0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
21bf0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
21c00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
21c10 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20  **.** {F15306}  
21c20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
21c30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21c40 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69   stops because i
21c50 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20  t is ready.**   
21c60 20 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72          to retur
21c70 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  n another row of
21c80 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c   the result set,
21c90 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20   it returns.**  
21ca0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
21cb0 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  _ROW]..**.** {F1
21cc0 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c  5308}  If a call
21cd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
21ce0 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73  p(S)] encounters
21cf0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
21d00 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
21d10 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f  upt|interrupt] o
21d20 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  r a run-time err
21d30 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
21d40 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61   it returns an a
21d50 70 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72  ppropraite error
21d60 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f   code that is no
21d70 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20  t one of.**     
21d80 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
21d90 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
21da0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
21db0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30  ]..**.** {F15310
21dc0 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  }  If an [sqlite
21dd0 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65  3_interrupt|inte
21de0 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69  rrupt] or run-ti
21df0 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
21e00 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
21e10 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
21e20 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
21e30 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
21e40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21e50 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
21e60 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
21e70 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
21e80 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
21e90 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
21ea0 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
21eb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
21ec0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
21ed0 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  on returns eithe
21ee0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
21ef0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b  SQLITE_ERROR], [
21f00 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72  SQLITE_BUSY], or
21f10 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
21f20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21f30 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
21f40 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
21f50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
21f60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
21f70 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30  sult set {F13770
21f80 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
21f90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
21fa0 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
21fb0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
21fc0 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
21fd0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
21fe0 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65  * {F13771}  Afte
21ff0 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
22000 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
22010 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  at returns.**   
22020 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
22030 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74  ROW], the [sqlit
22040 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
22050 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20  ] routine.**    
22060 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75         will retu
22070 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
22080 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  e as the.**     
22090 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
220a0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
220b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
220c0 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20  {F13772}  After 
220d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
220e0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61  ] has returned a
220f0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
22100 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
22110 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
22120 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
22130 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65  _step(S)] has be
22140 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  en .**          
22150 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b   called on the [
22160 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22170 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  nt] for.**      
22180 20 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74       the first t
22190 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
221a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
221b0 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20  e|prepared].**  
221c0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
221d0 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74  ite3_reset|reset
221e0 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ], the [sqlite3_
221f0 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a  data_count(S)].*
22200 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  *           rout
22210 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
22220 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22230 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
22240 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22260 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
22270 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35  atatypes {F10265
22280 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  }.** KEYWORDS: S
22290 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
222a0 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76   {F10266}Every v
222b0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
222c0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
222d0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
222e0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
222f0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
22300 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
22310 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
22320 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
22330 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
22340 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
22350 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
22360 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  L.** </ul> {END}
22370 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
22380 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
22390 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
223a0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
223b0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
223c0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
223d0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
223e0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
223f0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
22400 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
22410 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
22420 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
22430 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
22440 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22450 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
22460 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
22470 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e  e SQLITE3_TEXT n
22480 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
22490 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
224a0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
224b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
224c0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
224d0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
224e0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
224f0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
22500 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
22510 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
22520 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
22530 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
22540 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
22550 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
22560 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
22570 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73  API3REF: Results
22580 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
22590 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a  uery {F13800}.**
225a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
225b0 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
225c0 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69  ult set query" i
225d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
225e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
225f0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
22600 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e  n about.** a sin
22610 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
22620 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74  e current result
22630 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
22640 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61    In every.** ca
22650 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
22660 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
22670 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70  er to the .** [p
22680 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22690 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
226a0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74  .** evaluated (t
226b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
226c0 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75  *] that was retu
226d0 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  rned from .** [s
226e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
226f0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
22700 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64  ts variants) and
22710 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61  .** the second a
22720 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
22730 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
22740 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
22750 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f  ormation .** sho
22760 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
22770 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20    The left-most 
22780 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
22790 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20  sult set.** has 
227a0 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a  an index of 0..*
227b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
227c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
227d0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
227e0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
227f0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68   or if the.** th
22800 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  e column index i
22810 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
22820 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
22830 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65  defined. .** The
22840 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
22850 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
22860 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
22870 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
22880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22890 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
228a0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
228b0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
228c0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
228d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
228e0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
228f0 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  l subsequently..
22900 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
22910 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
22920 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
22930 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22940 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
22950 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
22960 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
22970 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
22980 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
22990 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
229a0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
229b0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
229c0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
229d0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
229e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
229f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22a00 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
22a10 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
22a20 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
22a30 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
22a40 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
22a50 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
22a60 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
22a70 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20  efined.  .**.** 
22a80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
22a90 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
22aa0 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  e returns .** [S
22ab0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
22ac0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
22ad0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
22ae0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
22af0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
22b00 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
22b10 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
22b20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
22b30 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
22b40 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
22b50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
22b60 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
22b70 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
22b80 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
22b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
22ba0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
22bb0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
22bc0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
22bd0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
22be0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
22bf0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
22c00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
22c10 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
22c20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
22c30 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
22c40 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
22c50 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
22c60 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
22c70 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
22c80 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
22c90 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
22ca0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
22cb0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
22cc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
22cd0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
22ce0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
22cf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22d00 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74  bytes() .** rout
22d10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
22d20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
22d30 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
22d40 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68  string..** If th
22d50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
22d60 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
22d70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
22d80 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
22d90 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
22da0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
22db0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
22dc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
22dd0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
22de0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
22df0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
22e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
22e10 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
22e20 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
22e30 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
22e40 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
22e50 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
22e60 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
22e70 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
22e80 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61  tring..** The va
22e90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65  lue returned doe
22ea0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  s not include th
22eb0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
22ec0 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  r at the end.** 
22ed0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
22ee0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
22ef0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22f00 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
22f10 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
22f20 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
22f30 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
22f40 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72  cters..**.** Str
22f50 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
22f60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22f70 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
22f80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22f90 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
22fa0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
22fb0 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
22fc0 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75  nated.  The retu
22fd0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
22fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22ff0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
23000 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73  o-length blob is
23010 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a   an arbitrary.**
23020 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62   pointer, possib
23030 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70  ly even a NULL p
23040 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
23050 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
23060 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
23070 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
23080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23090 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
230a0 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
230b0 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   in UTF-16 in na
230c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
230d0 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
230e0 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20  .  .** The zero 
230f0 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
23100 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
23110 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
23120 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
23130 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
23140 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
23150 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
23160 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23170 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
23180 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
23190 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
231a0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
231b0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
231c0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
231d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
231e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
231f0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
23200 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23210 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
23220 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
23230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
23240 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
23250 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
23260 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
23270 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
23280 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ke .** [sqlite3_
23290 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
232a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
232b0 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  t()], or [sqlite
232c0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
232d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
232e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
232f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
23300 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
23310 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
23320 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
23330 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
23340 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
23350 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
23360 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
23370 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
23380 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
23390 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
233a0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
233b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
233c0 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69   do the conversi
233d0 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  on.** automatica
233e0 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
233f0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
23400 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
23410 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70  s that.** are ap
23420 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
23430 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
23440 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
23450 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
23460 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
23470 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
23480 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
23490 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
234a0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
234b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
234c0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
234d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
234e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
234f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
23500 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
23510 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
23520 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
23530 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
23540 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
23550 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
23560 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
23570 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
23580 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
23590 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
235a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
235b0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
235c0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
235d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
235e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
235f0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
23600 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
23610 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
23620 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
23630 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
23640 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d   as for INTEGER-
23650 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
23660 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
23670 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
23680 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
23690 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
236a0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
236b0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
236c0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
236d0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
236e0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
236f0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
23700 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
23710 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
23720 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
23730 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
23740 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
23750 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
23760 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
23770 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
23780 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
23790 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
237a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
237b0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
237c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
237d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
237e0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
237f0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
23800 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
23810 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
23820 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
23830 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
23840 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
23850 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
23860 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
23870 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
23880 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
23890 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
238a0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
238b0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  e>.**.** The tab
238c0 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
238d0 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
238e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
238f0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
23900 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
23910 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
23920 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
23930 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
23940 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71  has its.** on eq
23950 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uavalent interna
23960 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
23970 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
23980 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
23990 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
239a0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
239b0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
239c0 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
239d0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
239e0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
239f0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
23a00 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
23a10 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
23a20 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
23a30 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23a40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
23a50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23a60 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
23a70 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
23a80 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
23a90 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a   invalidated. .*
23aa0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
23ab0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
23ac0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
23ad0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
23ae0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
23af0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
23b00 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69  * <li><p>  The i
23b10 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
23b20 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
23b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23b40 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  () .**          
23b50 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
23b60 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
23b70 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
23b80 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
23b90 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20  *          need 
23ba0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
23bb0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f  he string.</p></
23bc0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70  li>.**.** <li><p
23bd0 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  >  The initial c
23be0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
23bf0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
23c00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
23c10 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
23c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23c30 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
23c40 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
23c50 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
23c60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
23c70 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c  o UTF-16.</p></l
23c80 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
23c90 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
23ca0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
23cb0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
23cc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23cd0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
23ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23cf0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
23d00 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
23d10 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
23d20 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54  *          to UT
23d30 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  F-8.</p></li>.**
23d40 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
23d50 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
23d60 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
23d70 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
23d80 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
23d90 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
23da0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
23db0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
23dc0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
23dd0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
23de0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
23df0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
23e00 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
23e10 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
23e20 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
23e30 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
23e40 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
23e50 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
23e60 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
23e70 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74  ime it is.** not
23e80 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
23e90 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
23ea0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
23eb0 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a  invalidated.  .*
23ec0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
23ed0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
23ee0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
23ef0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
23f00 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
23f10 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
23f20 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
23f30 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  *  <ul>.**  <li>
23f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23f50 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
23f60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23f70 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
23f80 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
23f90 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
23fa0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
23fb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
23fc0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
23fd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23fe0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
23ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24000 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
24010 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e    </ul>.**.** In
24020 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
24030 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
24040 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24050 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t(), sqlite3_col
24060 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f  umn_blob(),.** o
24070 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
24080 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
24090 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
240a0 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73  ult into the des
240b0 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20  ired.** format, 
240c0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
240d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
240e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
240f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
24100 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69  o.** find the si
24110 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
24120 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
24130 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
24140 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
24150 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
24160 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
24170 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
24180 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20  lumn_bytes16(). 
24190 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d   And do not.** m
241a0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
241b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
241c0 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  6() with calls t
241d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
241e0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
241f0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
24200 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
24210 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
24220 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
24230 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
24240 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
24250 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24260 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
24270 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
24280 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
24290 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
242a0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
242b0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
242c0 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69  s.** and blobs i
242d0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
242e0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
242f0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
24300 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
24310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
24320 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
24330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24340 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20  t()], etc. into 
24350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
24360 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  e()]..**.** If a
24370 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
24380 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
24390 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
243a0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
243b0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
243c0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
243d0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
243e0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
243f0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
24400 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
24410 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
24420 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
24430 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
24440 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
24450 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
24460 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
24470 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
24480 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
24490 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
244a0 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65  .** {F13803} The
244b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
244c0 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
244d0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
244e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
244f0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
24500 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
24510 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
24520 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
24530 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24540 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f  nt] S into a blo
24550 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  b and then retur
24560 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
24570 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
24580 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
24590 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20  .**.** {F13806} 
245a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
245b0 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20  umn_bytes(S,N)] 
245c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
245d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
245e0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
245f0 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72  s in the blob or
24600 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
24610 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
24620 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
24630 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
24640 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
24650 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
24660 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
24670 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
24680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24690 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  ob(S,N)] or.**  
246a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
246b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
246c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  )]..**.** {F1380
246d0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
246e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53  column_bytes16(S
246f0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24700 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
24710 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
24720 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
24730 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
24740 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
24750 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
24760 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
24770 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
24780 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
24790 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
247a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
247b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
247c0 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6(S,N)]..**.** {
247d0 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c  F13812} The [sql
247e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
247f0 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  le(S,N)] interfa
24800 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
24810 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24820 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24830 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24840 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24850 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24870 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69   S into a floati
24880 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61  ng point value a
24890 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
248a0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
248b0 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a   that value..**.
248c0 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20  ** {F13815} The 
248d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
248e0 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  int(S,N)] interf
248f0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
24900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24910 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
24920 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
24930 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
24940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24950 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24960 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
24970 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24980 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
24990 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
249a0 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
249b0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
249c0 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b  * {F13818} The [
249d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
249e0 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72  nt64(S,N)] inter
249f0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
24a00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
24a10 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
24a20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
24a30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
24a40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
24a50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24a60 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
24a70 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
24a80 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
24a90 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
24aa0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
24ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d  ..**.** {F13821}
24ac0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24ad0 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
24ae0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
24af0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
24b00 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
24b10 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
24b20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
24b30 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
24b40 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24b50 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
24b60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24b70 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20   UTF-8 .**      
24b80 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
24b90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
24ba0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
24bb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20  .**.** {F13824} 
24bc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24bd0 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
24be0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
24bf0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
24c00 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
24c10 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
24c20 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
24c30 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
24c40 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
24c50 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
24c60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
24c70 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
24c80 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
24c90 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
24ca0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
24cb0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
24cc0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
24cd0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
24ce0 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68  *.** {F13827} Th
24cf0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24d00 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
24d10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
24d20 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
24d30 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
24d40 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
24d50 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
24d60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
24d70 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
24d80 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
24d90 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
24da0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24db0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e Nth column in 
24dc0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24dd0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24de0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24df0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24e00 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
24e10 7b 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71  {F13830} The [sq
24e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
24e30 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ue(S,N)] interfa
24e40 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  ce returns a.** 
24e50 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
24e60 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   to an [unprotec
24e70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24e80 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68  e] object for th
24e90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
24ea0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
24eb0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
24ec0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
24ed0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
24ee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24ef0 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  t] S..*/.const v
24f00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24f10 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
24f20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24f30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24f40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
24f50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24f60 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
24f70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24f80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24f90 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
24fa0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
24fb0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
24fc0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24fd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24fe0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
24ff0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25000 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
25010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25020 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
25030 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25040 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
25050 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25060 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
25070 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25080 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
25090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
250a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
250b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
250c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
250d0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
250e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
250f0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
25100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
25110 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
25120 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
25130 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25140 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
25150 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
25160 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a  ect {F13300}.**.
25170 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
25180 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
25190 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
251a0 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72  delete a .** [pr
251b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
251c0 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  ]. If the statem
251d0 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75  ent was.** execu
251e0 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
251f0 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  , or not execute
25200 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53  d at all, then S
25210 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
25220 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63  rned..** If exec
25230 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
25240 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
25250 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72  en an .** [error
25260 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
25270 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a  ded error code].
25280 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
25290 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
252a0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
252b0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
252c0 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
252d0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
252e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
252f0 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74  t].  If the virt
25300 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
25310 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  not .** complete
25320 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e  d execution when
25330 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
25340 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73   called, that is
25350 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74   like.** encount
25360 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f  ering an error o
25370 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20  r an interrupt. 
25380 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69   (See [sqlite3_i
25390 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a  nterrupt()].) .*
253a0 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
253b0 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
253c0 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
253d0 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c  sactions cancell
253e0 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69  ed,  .** dependi
253f0 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
25400 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
25410 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
25420 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
25430 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
25440 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
25450 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  NTS:.**.** {F113
25460 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
25470 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e  _finalize(S)] in
25480 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73  terface destroys
25490 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
254a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
254b0 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65  ment] S and rele
254c0 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ases all.**     
254d0 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
254e0 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68  file resources h
254f0 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65  eld by that obje
25500 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  ct..**.** {F1130
25510 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
25520 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
25530 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25540 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
25550 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
25560 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
25570 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a  ned an error,.**
25580 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
25590 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
255a0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61  (S)] returns tha
255b0 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f  t same error..*/
255c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
255d0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
255e0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
255f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
25600 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
25610 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
25620 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13330}.**.** Th
25630 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
25640 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
25650 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
25660 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25670 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
25680 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20  .** back to its 
25690 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
256a0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
256b0 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
256c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
256d0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
256e0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
256f0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
25700 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25710 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
25720 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
25730 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
25740 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
25750 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
25760 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
25770 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
25780 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {F11332} The [s
25790 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
257a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
257b0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
257c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
257d0 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
257e0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
257f0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
25800 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66  *.** {F11334} If
25810 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25820 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25830 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a  3_step(S)] for .
25840 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
25850 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25860 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
25870 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
25880 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
25890 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
258a0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
258b0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
258c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
258d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
258e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
258f0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
25900 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
25910 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65   {F11336} If the
25920 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
25930 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
25940 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  ep(S)] for.**   
25950 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
25960 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
25970 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
25980 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
25990 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
259a0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
259b0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
259c0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
259d0 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {F11338} The [s
259e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
259f0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
25a00 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
25a10 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
25a20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
25a30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
25a40 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72  ings] on [prepar
25a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
25a60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
25a70 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
25a80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
25a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
25aa0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
25ab0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  SQL Functions {F
25ac0 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  16100}.** KEYWOR
25ad0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
25ae0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
25af0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77   .**.** These tw
25b00 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
25b10 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
25b20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20  as.** "function 
25b30 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
25b40 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f 20  s") are used to 
25b50 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
25b60 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a  s or aggregates.
25b70 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  ** or to redefin
25b80 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
25b90 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
25ba0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
25bb0 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20  egates.  The.** 
25bc0 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20  difference only 
25bd0 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20  between the two 
25be0 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
25bf0 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
25c00 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
25c10 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
25c20 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
25c30 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
25c40 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
25c50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25c60 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
25c70 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
25c80 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
25c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
25ca0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25cb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25cc0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
25cd0 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
25ce0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
25cf0 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
25d00 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  le.** program us
25d10 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
25d20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25d30 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c  ction] internall
25d40 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66  y, then SQL.** f
25d50 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
25d60 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
25d70 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74  lly to each [dat
25d80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25d90 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  ]..**.** The sec
25da0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25db0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25dc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
25dd0 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
25de0 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
25df0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
25e00 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
25e10 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
25e20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
25e30 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
25e40 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
25e50 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
25e60 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
25e70 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
25e80 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
25e90 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
25ea0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25eb0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
25ec0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
25ed0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
25ee0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
25ef0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
25f00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
25f10 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
25f20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25f30 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
25f40 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
25f50 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
25f60 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
25f70 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
25f80 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
25f90 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
25fa0 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
25fb0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
25fc0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
25fd0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
25fe0 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
25ff0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
26000 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
26010 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
26020 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
26030 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
26040 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
26050 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
26060 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
26070 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
26080 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
26090 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
260a0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
260b0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
260c0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
260d0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
260e0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
260f0 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
26100 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
26110 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26120 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
26130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
26140 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
26150 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
26160 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
26170 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
26180 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
26190 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
261a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
261b0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
261c0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
261d0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
261e0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
261f0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
26200 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
26210 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
26220 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
26230 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
26240 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
26250 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
26260 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
26270 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
26280 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
26290 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
262a0 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
262b0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
262c0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
262d0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
262e0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
262f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
26300 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
26310 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
26320 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
26330 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
26340 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
26350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
26360 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
26370 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
26380 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
26390 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
263a0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
263b0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
263c0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
263d0 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
263e0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
263f0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
26400 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
26410 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
26420 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
26430 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
26440 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
26450 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
26460 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
26470 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
26480 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
26490 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
264a0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
264b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
264c0 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
264d0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
264e0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
264f0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
26500 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
26510 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
26520 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
26530 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
26540 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
26550 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
26560 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
26570 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
26580 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
26590 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
265a0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
265b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
265c0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
265d0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
265e0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
265f0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
26600 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
26610 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
26620 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
26630 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
26640 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
26650 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
26660 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
26670 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
26680 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   used..**.** INV
26690 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
266a0 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  F16103} The [sql
266b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
266c0 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66  tion16()] interf
266d0 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63  ace behaves exac
266e0 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
266f0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72  like [sqlite3_cr
26700 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
26710 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78   in every way ex
26720 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20  cept that it.** 
26730 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72           interpr
26740 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f  ets the zFunctio
26750 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61  nName argument a
26760 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  s.**          ze
26770 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
26780 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
26790 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
267a0 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  f as a.**       
267b0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
267c0 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  ed UTF-8..**.** 
267d0 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65  {F16106} A succe
267e0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
267f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
26800 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
26810 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
26820 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,N,E,...)] inter
26830 66 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a  face registers.*
26840 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65  *          or re
26850 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20  places callback 
26860 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61  functions in [da
26870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26880 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
26890 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
268a0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
268b0 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68  ion named X with
268c0 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
268d0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61            and ha
268e0 76 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 64  ving a perferred
268f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
26900 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  f E..**.** {F161
26910 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  09} A successful
26920 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26930 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26940 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
26950 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
26960 72 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20  replaces the P, 
26970 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75  F, S, and L valu
26980 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f  es from any prio
26990 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20  r calls with.** 
269a0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
269b0 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45  e D, X, N, and E
269c0 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b   values..**.** {
269d0 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  F16112} The [sql
269e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
269f0 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69  tion(D,X,...)] i
26a00 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
26a10 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
26a20 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  a return code of
26a30 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26a40 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  if the SQL funct
26a50 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a  ion name X is.**
26a60 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72            longer
26a70 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20   than 255 bytes 
26a80 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
26a90 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
26aa0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d  ..**.** {F16118}
26ab0 20 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62   Either F must b
26ac0 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  e NULL and S and
26ad0 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20   L are non-NULL 
26ae0 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20  or else F.**    
26af0 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c        is non-NUL
26b00 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
26b10 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73  e NULL, otherwis
26b20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
26b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26b40 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
26b50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73  ,F,S,L)] returns
26b60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
26b70 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20  .**.** {F16121} 
26b80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
26b90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
26ba0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
26bb0 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
26bc0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
26bd0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
26be0 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
26bf0 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
26c00 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
26c10 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
26c20 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
26c30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26c40 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34  D..**.** {F16124
26c50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
26c60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
26c70 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
26c80 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
26c90 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
26ca0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
26cb0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
26cc0 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63  arameter N (spec
26cd0 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ifying the numbe
26ce0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
26cf0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
26d00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62  e SQL function b
26d10 65 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29  eing registered)
26d20 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20   is less.**     
26d30 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20       than -1 or 
26d40 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
26d50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d  ..**.** {F16127}
26d60 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e   When N is non-n
26d70 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71  egative, the [sq
26d80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26d90 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
26da0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
26db0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63  terface causes c
26dc0 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
26dd0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
26de0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
26df0 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20          named X 
26e00 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  when the number 
26e10 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
26e20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26e30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
26e40 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a  exactly N..**.**
26e50 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e   {F16130} When N
26e60 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c   is -1, the [sql
26e70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26e80 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
26e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
26ea0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
26eb0 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
26ec0 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
26ed0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
26ee0 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
26ef0 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ith any number o
26f00 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
26f10 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e  ** {F16133} When
26f20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
26f30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26f40 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
26f50 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
26f60 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
26f70 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
26f80 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
26f90 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   X.**          a
26fa0 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c  nd when one impl
26fb0 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e  ementation has N
26fc0 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65  >=0 and the othe
26fd0 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20  r has N=(-1).** 
26fe0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70           the imp
26ff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
27000 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73   a non-zero N is
27010 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
27020 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20  * {F16136} When 
27030 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
27040 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27050 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a  n(D,X,N,E,...)].
27060 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
27070 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
27080 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
27090 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
270a0 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  n X with.**     
270b0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75       the same nu
270c0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
270d0 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66  s N but with dif
270e0 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  ferent.**       
270f0 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20     encodings E, 
27100 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  then the impleme
27110 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20  ntation where E 
27120 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20  matches the.**  
27130 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
27140 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65   encoding is pre
27150 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ferred..**.** {F
27160 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67  16139} For an ag
27170 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
27180 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69  tion created usi
27190 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
271a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
271b0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
271c0 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69  P,0,S,L)] the fi
271d0 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20  nializer.**     
271e0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20       function L 
271f0 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69  will always be i
27200 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
27210 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nce if the.**   
27220 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63         step func
27230 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64  tion S is called
27240 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
27250 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34  es..**.** {F1614
27260 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  2} When SQLite i
27270 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68  nvokes either th
27280 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70  e xFunc or xStep
27290 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20   function of.** 
272a0 20 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c           an appl
272b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
272c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
272d0 61 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65  aggregate create
272e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
272f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27300 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20  _function()] or 
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 31 36 28 29 5d 2c 0a 2a  function16()],.*
27330 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
27340 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71  the array of [sq
27350 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27360 65 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74  ects passed as t
27370 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
27380 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61  hird parameter a
27390 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65  re always [prote
273a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
273b0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  ue] objects..*/.
273c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
273d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
273e0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
273f0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
27400 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
27410 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
27420 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
27430 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
27440 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
27450 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
27460 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
27470 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
27480 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
27490 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
274a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
274b0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
274c0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
274d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
274e0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
274f0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
27500 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
27510 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
27520 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
27530 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
27540 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
27550 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
27560 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
27570 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
27580 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
27590 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
275a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
275b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
275c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
275d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
275e0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20   Text Encodings 
275f0 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54  {F10267}.**.** T
27600 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
27610 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
27620 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
27630 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
27640 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
27650 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
27660 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
27670 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
27680 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
27690 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
276a0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
276b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
276c0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
276d0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
276e0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
276f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
27700 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
27710 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
27720 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
27730 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27740 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
27750 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27760 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
27770 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
27780 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
27790 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
277a0 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75  REF: Obsolete Fu
277b0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
277c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
277d0 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65  e all now obsole
277e0 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  te.  In order to
277f0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
27800 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
27810 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
27820 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75  code, we continu
27830 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20  e to support.** 
27840 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
27850 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64    However, new d
27860 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65  evelopment proje
27870 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  cts should avoid
27880 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
27890 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
278a0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
278b0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
278c0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
278d0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
278e0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
278f0 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74   tell you want t
27900 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  hey do..*/.int s
27910 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27920 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
27930 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71  ontext*);.int sq
27940 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
27950 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
27960 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
27970 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
27980 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
27990 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
279a0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
279b0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69  cover(void);.voi
279c0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
279d0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
279e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
279f0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
27a00 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
27a10 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
27a20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
27a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a40 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
27a50 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
27a60 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30  r Values {F15100
27a70 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  }.**.** The C-la
27a80 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
27a90 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
27aa0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
27ab0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
27ac0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
27ad0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
27ae0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
27af0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
27b00 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
27b10 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
27b20 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
27b30 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
27b40 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
27b50 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
27b60 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
27b70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27b80 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
27b90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27ba0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
27bb0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
27bc0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
27bd0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27be0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
27bf0 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
27c00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
27c10 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
27c20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
27c30 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
27c40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27c50 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
27c60 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
27c70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
27c80 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
27c90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
27ca0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
27cb0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
27cc0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
27cd0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
27ce0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27cf0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
27d00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27d10 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
27d20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27d30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
27d40 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
27d50 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
27d60 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
27d70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27d80 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
27d90 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
27da0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
27db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
27dc0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
27dd0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
27de0 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  ponding .** [sql
27df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27e00 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
27e10 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78  n_* routines] ex
27e20 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68  cept that .** th
27e30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
27e40 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
27e50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27e60 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  lue] object poin
27e70 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f  ter.** instead o
27e80 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  f an [sqlite3_st
27e90 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
27ea0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
27eb0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
27ec0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
27ed0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
27ee0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
27ef0 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a   UTF16 string.**
27f00 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
27f10 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
27f20 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
27f30 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
27f40 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
27f50 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
27f60 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
27f70 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
27f80 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73  ct UTF16 strings
27f90 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
27fa0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
27fb0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
27fc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27fd0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
27fe0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
27ff0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
28000 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
28010 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
28020 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
28030 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
28040 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
28050 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
28060 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
28070 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
28080 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
28090 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
280a0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
280b0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
280c0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
280d0 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75  ords if the valu
280e0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
280f0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
28100 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
28110 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
28120 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69  s done.  Otherwi
28130 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
28140 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a   occurs.  The .*
28150 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
28160 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
28170 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
28180 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
28190 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
281a0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
281b0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
281c0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  at the pointer t
281d0 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  hat.** is return
281e0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
281f0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
28200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28210 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
28220 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28230 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
28240 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
28250 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
28260 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
28270 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
28280 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
28290 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
282a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
282b0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
282c0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
282d0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72    .**.** These r
282e0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
282f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
28300 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
28310 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
28320 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
28330 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
28340 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
28350 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ..**.**.** INVAR
28360 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
28370 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5103} The [sqlit
28380 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
28390 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
283a0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
283b0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
283c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
283d0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62  bject V into a b
283e0 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
283f0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
28400 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
28410 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
28420 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36  e..**.** {F15106
28430 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
28440 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69  alue_bytes(V)] i
28450 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28460 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28470 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28480 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
28490 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
284a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
284b0 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
284c0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
284d0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
284e0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
284f0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
28500 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
28510 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
28520 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  (V)] or.**      
28530 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c      [sqlite3_val
28540 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a  ue_text(V)]..**.
28550 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20  ** {F15109} The 
28560 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
28570 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72  ytes16(V)] inter
28580 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
285a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
285b0 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
285c0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
285d0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
285e0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
285f0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
28600 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
28610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
28620 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
28630 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28640 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20  text16(V)],.**  
28650 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
28660 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
28670 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  V)], or [sqlite3
28680 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
28690 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  V)]..**.** {F151
286a0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
286b0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29  _value_double(V)
286c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
286d0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
286e0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
286f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28700 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66  bject V into a f
28710 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
28720 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
28730 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
28740 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
28750 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d  ..**.** {F15115}
28760 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28770 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65  lue_int(V)] inte
28780 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28790 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
287a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
287b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
287c0 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
287d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
287e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
287f0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
28800 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
28810 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
28820 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71  {F15118} The [sq
28830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
28840 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  4(V)] interface 
28850 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28860 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
28870 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28880 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28890 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
288a0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
288b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
288c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
288d0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
288e0 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  F15121} The [sql
288f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
28900 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
28910 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
28920 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
28930 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28940 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
28950 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
28960 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20   UTF-8 .**      
28970 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
28980 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28990 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
289a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20  .**.** {F15124} 
289b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
289c0 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e  ue_text16(V)] in
289d0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
289e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
289f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
28a00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28a10 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
28a20 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
28a30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
28a40 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
28a50 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
28a60 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
28a70 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
28a80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
28a90 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
28aa0 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  15127} The [sqli
28ab0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28ac0 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  be(V)] interface
28ad0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28ae0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
28af0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28b00 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
28b10 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28b20 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
28b30 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
28b40 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
28b50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
28b60 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
28b70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
28b80 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
28b90 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71  {F15130} The [sq
28ba0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28bb0 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61  16le(V)] interfa
28bc0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
28bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
28be0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28bf0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
28c00 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
28c10 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
28c20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
28c30 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
28c40 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
28c50 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
28c60 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28c70 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
28c80 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68  *.** {F15133} Th
28c90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28ca0 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
28cb0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
28cc0 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b          one of [
28cd0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53  SQLITE_NULL], [S
28ce0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
28cf0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a  [SQLITE_FLOAT],.
28d00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
28d10 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53  ITE_TEXT], or [S
28d20 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
28d30 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
28d40 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
28d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28d60 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
28d70 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c  F15136} The [sql
28d80 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
28d90 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ic_type(V)] inte
28da0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a  rface converts.*
28db0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
28dc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28dd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28de0 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e  V into either an
28df0 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20   integer or.**  
28e00 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69          a floati
28e10 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69  ng point value i
28e20 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77  f it can do so w
28e30 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a  ithout loss of.*
28e40 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72  *          infor
28e50 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75  mation, and retu
28e60 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  rns one of [SQLI
28e70 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20  TE_NULL],.**    
28e80 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e        [SQLITE_IN
28e90 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
28ea0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
28eb0 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  TEXT], or.**    
28ec0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c        [SQLITE_BL
28ed0 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
28ee0 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
28ef0 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
28f00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28f10 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20   object V after 
28f20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  the conversion a
28f30 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  ttempt..*/.const
28f40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
28f50 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
28f60 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
28f80 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
28f90 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
28fa0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
28fb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
28fc0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
28fd0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
28fe0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
28ff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
29000 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
29010 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
29020 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
29030 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
29040 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
29050 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
29060 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
29070 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
29080 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29090 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
290a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
290b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
290c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
290d0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
290e0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
290f0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
29100 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
29110 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
29120 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
29130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29140 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
29150 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
29160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29180 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
29190 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
291a0 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a  ext {F16210}.**.
291b0 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
291c0 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
291d0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
291e0 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
291f0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
29200 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
29210 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
29220 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66  tate.  .** The f
29230 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
29240 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29250 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e  context() routin
29260 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  e is.** is calle
29270 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  d for a particul
29280 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51  ar aggregate, SQ
29290 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e  Lite allocates n
292a0 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  Bytes of memory.
292b0 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65  ** zeros that me
292c0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
292d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
292e0 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20  t..** On second 
292f0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
29300 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
29310 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
29320 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  t().** for the s
29330 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
29340 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68  nction index, th
29350 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
29360 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
29370 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29380 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65  .** of the aggre
29390 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65  gate can use the
293a0 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72   returned buffer
293b0 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64   to accumulate d
293c0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ata..**.** SQLit
293d0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
293e0 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61  frees the alloca
293f0 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20  ted buffer when 
29400 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
29410 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
29420 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
29430 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  t parameter shou
29440 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  ld be a copy of 
29450 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
29460 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
29470 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
29480 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
29490 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
294a0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
294b0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
294c0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
294d0 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
294e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
294f0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
29500 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
29510 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
29520 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
29530 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
29540 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
29550 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29560 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68  *.** {F16211} Th
29570 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
29580 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61  on of [sqlite3_a
29590 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
295a0 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  (C,N)] for.**   
295b0 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75         a particu
295c0 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
295d0 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  an aggregate fun
295e0 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72  ction (for a par
295f0 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20  ticular.**      
29600 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63      context C) c
29610 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
29620 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74  allocation N byt
29630 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
29640 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
29650 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
29660 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
29670 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 69   to the allocati
29680 6f 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oned.**         
29690 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b   memory..**.** {
296a0 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d  F16213} If a mem
296b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
296c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
296d0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
296e0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
296f0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
29700 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
29710 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a  n returns 0..**.
29720 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f  ** {F16215} Seco
29730 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
29740 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  t invocations of
29750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29760 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29770 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
29780 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65  r the same conte
29790 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20  xt pointer C.** 
297a0 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20           ignore 
297b0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
297c0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
297d0 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65  nter to the same
297e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f  .**          blo
297f0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74  ck of memory ret
29800 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72  urned by the fir
29810 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  st invocation..*
29820 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68  *.** {F16217} Th
29830 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
29840 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61  ed by [sqlite3_a
29850 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29860 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20  (C,N)] is.**    
29870 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61        automatica
29880 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65  lly freed on the
29890 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73   next call to [s
298a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
298b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
298c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
298d0 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ()] for the [pre
298e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
298f0 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
29900 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72          the aggr
29910 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61  egate function a
29920 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63  ssociated with c
29930 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69  ontext C..*/.voi
29940 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
29950 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
29960 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
29970 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
29980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
29990 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
299a0 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a  ions {F16240}.**
299b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
299c0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
299d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
299e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
299f0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
29a00 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
29a10 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
29a20 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
29a30 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74  f the the [sqlit
29a40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29a50 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
29a60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29a70 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
29a80 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
29a90 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
29aa0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
29ab0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
29ac0 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  on. {END}.**.** 
29ad0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
29ae0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
29af0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
29b00 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
29b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29b20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
29b30 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
29b40 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
29b50 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b  * {F16243} The [
29b60 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
29b70 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  a(C)] interface 
29b80 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
29b90 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
29ba0 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    P pointer from
29bb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
29bc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
29bd0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
29be0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
29bf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29c00 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
29c10 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
29c20 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
29c30 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
29c40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
29c50 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
29c60 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
29c70 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
29c80 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
29c90 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
29ca0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
29cb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29cc0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
29cd0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
29ce0 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F16250}.**.** 
29cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
29d00 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
29d10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29d20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
29d30 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
29d40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29d50 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
29d60 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
29d70 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74  f the the [sqlit
29d80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29d90 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
29da0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29db0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
29dc0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
29dd0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
29de0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
29df0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
29e00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
29e10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
29e20 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  253} The [sqlite
29e30 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
29e40 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63  dle(C)] interfac
29e50 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
29e60 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
29e70 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72      D pointer fr
29e80 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
29e90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
29ea0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
29eb0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
29ec0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29ed0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
29ee0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
29ef0 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
29f00 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
29f10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
29f20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29f40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
29f50 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
29f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
29f70 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
29f80 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
29f90 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
29fa0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
29fb0 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a  ata {F16270}.**.
29fc0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
29fd0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
29fe0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
29ff0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2a000 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2a010 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74  te meta-data wit
2a020 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
2a030 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
2a040 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
2a050 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
2a060 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2a070 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
2a080 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
2a090 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
2a0a0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
2a0b0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
2a0c0 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20  iated meta-data 
2a0d0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2a0e0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2a0f0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2a100 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2a110 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2a120 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2a130 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2a140 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2a150 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2a160 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2a170 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2a180 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  -data associated
2a190 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
2a1a0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
2a1b0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2a1c0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
2a1d0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
2a1e0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2a1f0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
2a200 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
2a210 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2a220 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2a230 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
2a240 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
2a250 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
2a260 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
2a270 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
2a280 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2a290 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2a2a0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2a2b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2a2c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
2a2d0 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  a-data.** associ
2a2e0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
2a2f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2a300 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
2a310 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2a320 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
2a330 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a340 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2a350 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74  * If no meta-dat
2a360 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20  a has been ever 
2a370 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2a380 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   Nth.** argument
2a390 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2a3a0 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72  , or if the coor
2a3b0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
2a3c0 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
2a3d0 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2a3e0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2a3f0 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71  was set, then sq
2a400 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2a410 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  a().** returns a
2a420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2a430 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a440 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2a450 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2a460 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
2a470 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2a480 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2a490 61 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  as the meta-data
2a4a0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
2a4b0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2a4c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a4d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
2a4e0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
2a4f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
2a500 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
2a510 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
2a520 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
2a530 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
2a540 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20  oyed. .** If it 
2a550 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
2a560 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2a570 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a  the destructor .
2a580 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
2a590 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
2a5a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a5b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2a5c0 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64  on.** the meta-d
2a5d0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
2a5e0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
2a5f0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
2a600 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
2a610 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a620 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
2a630 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
2a640 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
2a650 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
2a660 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
2a670 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64   and drop meta-d
2a680 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61  ata on.** any pa
2a690 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66  rameter of any f
2a6a0 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74  unction at any t
2a6b0 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67  ime.  The only g
2a6c0 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74  uarantee.** is t
2a6d0 68 61 74 20 74 68 65 20 64 65 73 74 72 75 63 74  hat the destruct
2a6e0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
2a6f0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
2a700 61 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70  adata is.** drop
2a710 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72  ped..**.** In pr
2a720 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74  actice, meta-dat
2a730 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2a740 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2a750 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2a760 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2a770 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2a780 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2a790 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2a7a0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2a7b0 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
2a7c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2a7d0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2a7e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2a7f0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2a800 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2a810 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2a820 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2a830 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32  S:.**.** {F16272
2a840 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
2a850 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
2a860 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2a870 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2a880 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
2a890 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2a8a0 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
2a8b0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2a8c0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2a8d0 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
2a8e0 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
2a8f0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
2a900 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2a910 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
2a920 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
2a930 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
2a940 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
2a950 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2a960 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
2a970 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
2a980 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
2a990 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
2a9a0 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2a9b0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2a9c0 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
2a9d0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  t.**          C.
2a9e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20  .**.** {F16276} 
2a9f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2aa00 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2aa10 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c  r D with a singl
2aa20 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  e argument.**   
2aa30 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20         which is 
2aa40 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69  the metadata poi
2aa50 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67  nter P following
2aa60 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
2aa70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2aa80 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2aa90 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74  P,D)] when SQLit
2aaa0 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
2aab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2aac0 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a   metadata..**.**
2aad0 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65   {F16277} SQLite
2aae0 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20   ceases to hold 
2aaf0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20  metadata for an 
2ab00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  SQL function par
2ab10 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
2ab20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75     when the valu
2ab30 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65  e of that parame
2ab40 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  ter changes..**.
2ab50 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e  ** {F16278} When
2ab60 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2ab70 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2ab80 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2ab90 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20  destructor.**   
2aba0 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64         is called
2abb0 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d   for any prior m
2abc0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2abd0 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
2abe0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2abf0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20        context C 
2ac00 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e  and parameter N.
2ac10 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20  .**.** {F16279} 
2ac20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c  SQLite will call
2ac30 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72   destructors for
2ac40 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74   any metadata it
2ac50 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20   is holding.**  
2ac60 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72          in a par
2ac70 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65  ticular [prepare
2ac80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77  d statement] S w
2ac90 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  hen either.**   
2aca0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2acb0 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71  reset(S)] or [sq
2acc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2acd0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f  )] is called..*/
2ace0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2acf0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2ad00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2ad10 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2ad20 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2ad30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2ad40 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2ad50 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2ad60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ad70 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2ad80 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2ad90 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2ada0 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F10280}.**.** 
2adb0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
2adc0 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  l value for the 
2add0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
2ade0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
2adf0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
2ae00 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
2ae10 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2ae20 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
2ae30 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
2ae40 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2ae50 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2ae60 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2ae70 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2ae80 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2ae90 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2aea0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2aeb0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2aec0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
2aed0 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e   .** SQLITE_TRAN
2aee0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2aef0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2af00 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2af10 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2af20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2af30 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2af40 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2af50 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2af60 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2af70 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2af80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2af90 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2afa0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2afb0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2afc0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2afd0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2afe0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2aff0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2b000 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2b010 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2b020 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2b030 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2b040 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2b050 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2b060 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2b070 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2b080 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2b090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2b0a0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2b0b0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2b0c0 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a  on {F16400}.**.*
2b0d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2b0e0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
2b0f0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
2b100 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
2b110 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
2b120 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2b130 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
2b140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2b150 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2b160 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2b170 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2b180 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
2b190 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2b1a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2b1b0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2b1c0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a  much like the .*
2b1d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b1e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2b1f0 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66  ind_*] family of
2b200 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a   functions used.
2b210 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ** to bind value
2b220 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
2b230 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
2b240 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
2b250 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  Refer to the.** 
2b260 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b270 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2b280 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  d_* documentatio
2b290 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  n] for.** additi
2b2a0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2b2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2b2c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2b2d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2b2e0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2b2f0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2b300 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2b310 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2b320 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2b330 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2b340 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2b350 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2b360 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2b370 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2b380 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2b390 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73  meter. .** The s
2b3a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2b3b0 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63  roblob() inerfac
2b3c0 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
2b3d0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2b3e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2b3f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2b400 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
2b410 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
2b420 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
2b430 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
2b440 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2b450 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b460 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
2b470 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2b480 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
2b490 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2b4a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2b4b0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2b4c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
2b4d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2b4e0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
2b4f0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
2b500 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2b510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b520 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2b530 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b540 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
2b550 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
2b560 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
2b570 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
2b580 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51  exception..** SQ
2b590 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
2b5a0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
2b5b0 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
2b5c0 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
2b5d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2b5e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
2b5f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
2b600 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
2b610 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2b620 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  .  SQLite interp
2b630 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
2b640 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
2b650 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2b660 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
2b670 55 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  UTF8. SQLite.** 
2b680 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
2b690 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2b6a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b6b0 36 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20  6() as UTF16 in 
2b6c0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
2b6d0 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
2b6e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2b6f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b700 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2b710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2b720 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
2b730 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2b740 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
2b750 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
2b760 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
2b770 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2b780 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
2b790 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2b7a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2b7b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2b7c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
2b7d0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2b7e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
2b7f0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2b800 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
2b810 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2b820 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
2b830 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2b840 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2b850 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b860 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2b870 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2b880 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
2b890 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63  outines make a c
2b8a0 6f 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79  opy private copy
2b8b0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
2b8c0 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
2b8d0 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
2b8e0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
2b8f0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
2b900 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
2b910 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
2b920 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
2b930 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
2b940 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  rm..** The sqlit
2b950 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2b960 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2b970 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2b980 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2b990 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2b9a0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2b9b0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2b9c0 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  on.  By default,
2b9d0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
2b9e0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
2b9f0 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e  OR.  A subsequen
2ba00 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2ba10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2ba20 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2ba30 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2ba40 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
2ba50 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
2ba60 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ERROR..**.** The
2ba70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ba80 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
2ba90 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2baa0 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  .** to throw an 
2bab0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
2bac0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
2bad0 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e  r BLOB is to lon
2bae0 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e  g.** to represen
2baf0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
2bb00 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
2bb10 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73  nterface.** caus
2bb20 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2bb30 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  ow an exception 
2bb40 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2bb50 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  the a.** memory 
2bb60 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
2bb70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2bb80 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2bb90 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2bba0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2bbb0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2bbc0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2bbd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2bbe0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
2bbf0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2bc00 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2bc10 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
2bc20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2bc30 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
2bc40 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2bc50 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2bc60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2bc70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2bc80 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2bc90 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2bca0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2bcb0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2bcc0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2bcd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2bce0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
2bcf0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2bd00 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2bd10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2bd20 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2bd30 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  be NULL..**.** T
2bd40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bd50 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
2bd60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2bd70 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ), .** sqlite3_r
2bd80 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
2bd90 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
2bda0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
2bdb0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
2bdc0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
2bdd0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
2bde0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2bdf0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
2be00 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
2be10 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
2be20 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
2be30 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2be40 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
2be50 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
2be60 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
2be70 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2be80 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61  ly..** SQLite ta
2be90 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
2bea0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
2beb0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
2bec0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2bed0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
2bee0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2bef0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66  nterfaces..** If
2bf00 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2bf10 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2bf20 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2bf30 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2bf40 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
2bf50 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
2bf60 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
2bf70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a   2nd parameter .
2bf80 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2bf90 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2bfa0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
2bfb0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2bfc0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2bfd0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2bfe0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
2bff0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
2c000 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
2c010 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
2c020 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
2c030 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
2c040 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
2c050 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
2c060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
2c070 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
2c080 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
2c090 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2c0a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c0b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2c0c0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2c0d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2c0e0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
2c0f0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2c100 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
2c110 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
2c120 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
2c130 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73  text or blob res
2c140 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
2c150 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
2c160 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
2c170 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
2c180 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2c190 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2c1a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2c1b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2c1c0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2c1d0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2c1e0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2c1f0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73  hen.** SQLite as
2c200 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2c210 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
2c220 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73  lt is constant s
2c230 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73  pace and.** does
2c240 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70   not copy the sp
2c250 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65  ace or call a de
2c260 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
2c270 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
2c280 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2c290 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
2c2a0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2c2b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c2c0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2c2d0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2c2e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2c2f0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2c300 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
2c310 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
2c320 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
2c330 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
2c340 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
2c350 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
2c360 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c370 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
2c380 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
2c390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c3a0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2c3b0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2c3c0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2c3d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c3e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2c3f0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2c400 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c410 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c420 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2c430 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2c440 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2c450 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2c460 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2c470 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
2c480 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2c490 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  so that [sqlite3
2c4a0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
2c4b0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
2c4c0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
2c4d0 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
2c4e0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2c4f0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2c500 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
2c510 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74  harm..** A [prot
2c520 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c530 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
2c540 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
2c550 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
2c560 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c570 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
2c580 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
2c590 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
2c5a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2c5b0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
2c5c0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
2c5d0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
2c5e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c5f0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2c600 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
2c610 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20  rent thread .** 
2c620 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
2c630 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
2c640 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c650 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
2c660 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  cieved.** the [s
2c670 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2c680 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
2c690 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2c6a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
2c6b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2c6c0 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
2c6d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
2c6e0 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
2c6f0 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
2c700 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20  ** {F16406} The 
2c710 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c720 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
2c730 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c740 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c750 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2c760 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2c770 65 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73  e a blob that is
2c780 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
2c790 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
2c7a0 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
2c7b0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
2c7c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20  .**.** {F16409} 
2c7d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2c7e0 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
2c7f0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c800 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c810 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c820 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c830 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
2c840 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
2c850 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54  **.** {F16412} T
2c860 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c870 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
2c880 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c890 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
2c8a0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
2c8b0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c8c0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
2c8d0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
2c8e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2c8f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
2c900 61 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73  a UTF8 error mes
2c910 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d  sage copied from
2c920 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20   V up to the.** 
2c930 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a           first z
2c940 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69  ero byte or unti
2c950 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65  l N bytes are re
2c960 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
2c970 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2c980 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
2c990 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c9a0 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
2c9b0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
2c9c0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2c9d0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2c9e0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2c9f0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2ca00 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2ca10 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
2ca20 52 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e  R] and a UTF16 n
2ca30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ca40 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
2ca50 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65  *          copie
2ca60 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74  d from V up to t
2ca70 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
2ca80 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69  rminator or unti
2ca90 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  l N bytes.**    
2caa0 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69        are read i
2cab0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
2cac0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20  .**.** {F16418} 
2cad0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2cae0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2caf0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
2cb00 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
2cb10 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
2cb20 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
2cb30 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
2cb40 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
2cb50 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
2cb60 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f       [SQLITE_TOO
2cb70 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72  BIG] and an appr
2cb80 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
2cb90 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssage..**.** {F1
2cba0 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6421} The [sqlit
2cbb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2cbc0 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66  nomem(C)] interf
2cbd0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
2cbe0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
2cbf0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
2cc00 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2cc10 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
2cc20 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
2cc30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2cc40 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20  E_NOMEM] and an 
2cc50 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
2cc60 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
2cc70 20 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73   {F16424} The [s
2cc80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2cc90 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69  ror_code(C,E)] i
2cca0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2ccb0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
2ccc0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
2ccd0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
2cce0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
2ccf0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
2cd00 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20  de E..**        
2cd10 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73    The error mess
2cd20 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68  age text is unch
2cd30 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  anged..**.** {F1
2cd40 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6427} The [sqlit
2cd50 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c  e3_result_int(C,
2cd60 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2cd70 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2cd80 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2cd90 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2cda0 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2cdb0 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
2cdc0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30  V..**.** {F16430
2cdd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2cde0 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29  esult_int64(C,V)
2cdf0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2ce00 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2ce10 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2ce20 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2ce30 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
2ce40 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e  integer value V.
2ce50 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20  .**.** {F16433} 
2ce60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2ce70 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74  ult_null(C)] int
2ce80 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2ce90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2cea0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2ceb0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2cec0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  NULL..**.** {F16
2ced0 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  436} The [sqlite
2cee0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2cef0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
2cf00 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2cf10 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cf20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2cf30 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
2cf40 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  TF8 string.**   
2cf50 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74         V up to t
2cf60 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
2cf70 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
2cf80 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
2cf90 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
2cfa0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
2cfb0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
2cfc0 20 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73   {F16439} The [s
2cfd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cfe0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  xt16(C,V,N,D)] i
2cff0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2d000 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d010 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2d020 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2d030 65 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69  e the UTF16 nati
2d040 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
2d050 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2d060 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
2d070 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a  st zero if N is.
2d080 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61  **          nega
2d090 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
2d0a0 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
2d0b0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2d0c0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2d0d0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
2d0e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2d0f0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2d100 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2d110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d120 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2d130 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2d140 65 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69  e UTF16 big-endi
2d150 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2d160 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
2d170 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2d180 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  N is.**         
2d190 20 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 20   is negative or 
2d1a0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
2d1b0 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e  s or V if N is n
2d1c0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
2d1d0 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20  ** {F16445} The 
2d1e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d1f0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2d200 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2d210 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2d220 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2d230 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2d240 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2d250 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2d260 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2d270 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
2d280 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a  st zero if N is.
2d290 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61  **          nega
2d2a0 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
2d2b0 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
2d2c0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2d2d0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2d2e0 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  48} The [sqlite3
2d2f0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c  _result_value(C,
2d300 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2d310 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2d320 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2d330 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2d340 20 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 63   to be [unprotec
2d350 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d360 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
2d370 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
2d380 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16451} The [sql
2d390 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2d3a0 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
2d3b0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2d3c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d3d0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2d3e0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2d3f0 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 20   N-byte blob of 
2d400 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
2d410 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {F16454} The [s
2d420 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d430 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
2d440 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d450 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
2d460 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
2d470 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
2d480 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
2d490 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
2d4a0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2d4b0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ning..**.** {F16
2d4c0 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
2d4d0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
2d4e0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
2d4f0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
2d500 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2d510 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2d520 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2d530 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
2d540 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2d550 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2d560 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2d570 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2d580 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2d590 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d5a0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
2d5b0 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
2d5c0 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
2d5d0 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
2d5e0 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
2d5f0 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
2d600 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
2d610 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
2d620 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
2d630 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
2d640 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
2d650 46 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  F16460} If the D
2d660 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
2d670 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d680 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
2d690 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2d6a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d6b0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
2d6c0 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
2d6d0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2d6e0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2d6f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2d700 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
2d710 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
2d720 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2d730 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
2d740 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
2d750 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
2d760 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
2d770 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
2d780 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
2d790 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2d7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
2d7b0 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
2d7c0 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
2d7d0 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66  *.** {F16463} If
2d7e0 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
2d7f0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
2d800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2d810 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
2d820 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d830 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2d840 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
2d850 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d860 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
2d870 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d880 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2d890 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
2d8a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2d8b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d8c0 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
2d8d0 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
2d8e0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
2d8f0 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
2d900 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
2d910 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
2d920 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a  ANSIENT] then .*
2d930 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
2d940 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2d950 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
2d960 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c  ith V as its onl
2d970 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20  y argument.**   
2d980 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68         when it h
2d990 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2d9a0 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f   the V value..*/
2d9b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d9c0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
2d9d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d9e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2d9f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2da00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2da10 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
2da20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
2da30 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
2da40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
2da50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2da60 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2da70 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2da80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2da90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2daa0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2dab0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2dac0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2dad0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2dae0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2daf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2db00 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
2db10 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2db20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2db30 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2db40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2db50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2db60 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
2db70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2db80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2db90 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
2dba0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2dbb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
2dbc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2dbd0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
2dbe0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2dbf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2dc00 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2dc10 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2dc20 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2dc30 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2dc40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2dc50 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
2dc60 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2dc70 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2dc80 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2dc90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2dca0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
2dcb0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2dcc0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2dcd0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2dce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2dcf0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
2dd00 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2dd10 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2dd20 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2dd30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2dd40 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
2dd50 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
2dd60 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
2dd70 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2dd80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2dd90 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
2dda0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ddb0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
2ddc0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b  ting Sequences {
2ddd0 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16600}.**.** Th
2dde0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2ddf0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
2de00 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
2de10 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
2de20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
2de30 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
2de40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2de50 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  t. .**.** The na
2de60 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
2de70 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2de80 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
2de90 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
2dea0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2deb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2dec0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
2ded0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2dee0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
2def0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
2df00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2df10 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20  llation16(). In 
2df20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65  all cases.** the
2df30 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20   name is passed 
2df40 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  as the second fu
2df50 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2df60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
2df70 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
2df80 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
2df90 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
2dfa0 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
2dfb0 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c  UTF16LE] or [SQL
2dfc0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
2dfd0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
2dfe0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
2dff0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
2e000 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
2e010 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
2e020 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
2e030 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
2e040 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
2e050 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
2e060 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2e070 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
2e080 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
2e090 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
2e0a0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74  UTF16_ALIGNED] t
2e0b0 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a  o indicate that.
2e0c0 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
2e0d0 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
2e0e0 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
2e0f0 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
2e100 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68  * of UTF16 in th
2e110 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2e120 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2e130 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
2e140 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
2e150 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
2e160 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
2e170 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
2e180 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
2e190 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
2e1a0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
2e1b0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
2e1c0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2e1d0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
2e1e0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
2e1f0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
2e200 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
2e210 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2e220 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
2e230 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
2e240 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
2e250 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
2e260 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20  assed as.** the 
2e270 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2e280 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2e290 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
2e2a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2e2b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2e2c0 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61   as its first pa
2e2d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
2e2e0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67  he remaining arg
2e2f0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70  uments to the ap
2e300 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
2e310 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
2e320 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
2e330 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
2e340 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61  by a (length, da
2e350 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta) pair and enc
2e360 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
2e370 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
2e380 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
2e390 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
2e3a0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
2e3b0 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
2e3c0 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e   registered. {EN
2e3d0 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  D} The applicati
2e3e0 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
2e3f0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
2e400 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
2e410 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
2e420 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74  positive if.** t
2e430 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
2e440 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
2e450 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
2e460 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
2e470 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e  nd.** string. i.
2e480 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
2e490 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
2e4a0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e4b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2e4c0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2e4d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e4e0 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20  ion().** excapt 
2e4f0 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
2e500 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
2e510 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
2e520 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
2e530 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
2e540 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2e550 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
2e560 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
2e570 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
2e580 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
2e590 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2e5a0 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
2e5b0 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
2e5c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e5d0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
2e5e0 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
2e5f0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a  estroyed when.**
2e600 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
2e610 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
2e620 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
2e630 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
2e640 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68  nctions.** or wh
2e650 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  en the [sqlite3*
2e660 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
2e670 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  e is closed usin
2e680 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
2e690 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
2e6a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2e6b0 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66  6603} A successf
2e6c0 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a  ul call to the.*
2e6d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e6e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e6f0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2e700 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  F,D)] interface.
2e710 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
2e720 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46  sters function F
2e730 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73   as the comparis
2e740 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64  on function used
2e750 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2e760 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74  implement collat
2e770 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 61  ion X on [databa
2e780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
2e790 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2e7a0 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e   databases havin
2e7b0 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a  g encoding E..**
2e7c0 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c  .** {F16604} SQL
2e7d0 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20  ite understands 
2e7e0 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
2e7f0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
2e800 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e810 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2e820 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a  E,P,F,D)] as a z
2e830 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2e840 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
2e850 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68   string in which
2e860 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64   case is ignored
2e870 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61   for ASCII chara
2e880 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20  cters and.**    
2e890 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69        is signifi
2e8a0 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43  cant for non-ASC
2e8b0 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  II characters..*
2e8c0 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75  *.** {F16606} Su
2e8d0 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74  ccessive calls t
2e8e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2e8f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2e900 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
2e910 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
2e920 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f  e same values fo
2e930 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f  r B, X, and E, o
2e940 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61  verride prior va
2e950 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
2e960 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e   of P, F, and D.
2e970 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20  .**.** {F16609} 
2e980 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  The destructor D
2e990 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   in [sqlite3_cre
2e9a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e9b0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
2e9c0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
2e9d0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69  t NULL then it i
2e9e0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72  s called with ar
2e9f0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68  gument P when th
2ea00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2ea10 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2ea20 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53   is dropped by S
2ea30 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  QLite..**.** {F1
2ea40 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6612} A collatin
2ea50 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
2ea60 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73  opped when it is
2ea70 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
2ea80 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f  ** {F16615} A co
2ea90 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2eaa0 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e   is dropped when
2eab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2eac0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
2ead0 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75       is closed u
2eae0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
2eaf0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ose()]..**.** {F
2eb00 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74  16618} The point
2eb10 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33  er P in [sqlite3
2eb20 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2eb30 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
2eb40 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
2eb50 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2eb60 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
2eb70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
2eb80 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
2eb90 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46        function F
2eba0 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75   for all subsequ
2ebb0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
2ebc0 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  of F..**.** {F16
2ebd0 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b  621} A call to [
2ebe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ebf0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
2ec00 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a  ,F)] is exactly.
2ec10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2ec20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74  same as a call t
2ec30 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2ec40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2ec50 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  ] with.**       
2ec60 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61     the same para
2ec70 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c  meters and a NUL
2ec80 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a  L destructor..**
2ec90 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c  .** {F16624} Fol
2eca0 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65  lowing a [sqlite
2ecb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ecc0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2ecd0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2ece0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2ecf0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
2ed00 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74  tion F for all t
2ed10 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a  ext comparison.*
2ed20 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61  *          opera
2ed30 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61  tions on [databa
2ed40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
2ed50 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20   on text values 
2ed60 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
2ed70 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69   use the collati
2ed80 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  ng sequence name
2ed90 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32   X..**.** {F1662
2eda0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2edb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2edc0 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77  16(B,X,E,P,F)] w
2edd0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a  orks the same.**
2ede0 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
2edf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ee00 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
2ee10 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
2ee20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2ee30 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20  ollation name X 
2ee40 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73  is understood as
2ee50 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2ee60 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2ee70 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64           instead
2ee80 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   of UTF-8..**.**
2ee90 20 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 6d   {F16630} When m
2eea0 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73  ultiple comparis
2eeb0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  on functions are
2eec0 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74   available for t
2eed0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
2eee0 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
2eef0 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63  quence, SQLite c
2ef00 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77  hooses the one w
2ef10 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69  hose text encodi
2ef20 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ng.**          r
2ef30 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
2ef40 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76  t amount of conv
2ef50 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20  ersion from the 
2ef60 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20  default.**      
2ef70 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e      text encodin
2ef80 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
2ef90 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2efa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2efb0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
2efc0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2efd0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2efe0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2eff0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2f000 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2f010 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2f020 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
2f030 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2f040 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
2f050 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2f060 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2f070 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2f080 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2f090 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2f0a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2f0b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2f0c0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2f0d0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2f0e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2f0f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2f100 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2f110 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2f120 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2f130 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2f140 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2f150 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2f160 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2f170 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2f180 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
2f190 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
2f1a0 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a  ks {F16700}.**.*
2f1b0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
2f1c0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2f1d0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2f1e0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2f1f0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2f200 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2f210 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2f220 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2f230 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2f240 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
2f250 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
2f260 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
2f270 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
2f280 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71  quence is.** req
2f290 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
2f2a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2f2b0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2f2c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2f2d0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2f2e0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
2f2f0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
2f300 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
2f310 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2f320 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
2f330 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
2f340 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66  F-8. {F16703} If
2f350 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2f360 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2f370 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73   used, the names
2f380 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61  .** are passed a
2f390 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2f3a0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2f3b0 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f  order. A call to
2f3c0 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74   either.** funct
2f3d0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
2f3e0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
2f3f0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
2f400 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2f410 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2f420 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2f430 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2f440 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2f450 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2f460 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f470 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2f480 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f490 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2f4a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2f4b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2f4c0 68 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 69  handle.  The thi
2f4d0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
2f4e0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
2f4f0 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
2f500 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2f510 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
2f520 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
2f530 73 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20  st.** desirable 
2f540 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
2f550 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66  ation sequence f
2f560 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
2f570 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  ..** The fourth 
2f580 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f590 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2f5a0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2f5b0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a  on sequence..**.
2f5c0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
2f5d0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
2f5e0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
2f5f0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
2f600 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2f610 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2f620 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
2f630 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2f640 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2f650 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2f660 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  ation_v2()]..**.
2f670 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2f680 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20  *.** {F16702} A 
2f690 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2f6a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
2f6b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50  ation_needed(D,P
2f6c0 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,F)].**         
2f6d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   or [sqlite3_col
2f6e0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2f6f0 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a  D,P,F)] causes.*
2f700 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2f710 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f720 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65  ion] D to invoke
2f730 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68   callback F with
2f740 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
2f750 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77     parameter P w
2f760 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73  henever it needs
2f770 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75   a comparison fu
2f780 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20  nction for a.** 
2f790 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
2f7a0 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74  ng sequence that
2f7b0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f   it does not kno
2f7c0 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b  w about..**.** {
2f7d0 46 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63  F16704} Each suc
2f7e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2f7f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2f800 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a  on_needed()] or.
2f810 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2f820 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f830 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72  eeded16()] overr
2f840 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ides the callbac
2f850 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  k registered.** 
2f860 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
2f870 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2f880 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72  onnection] by pr
2f890 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74  ior calls to eit
2f8a0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
2f8b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2f8c0 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61   {F16706} The na
2f8d0 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73  me of the reques
2f8e0 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ted collating fu
2f8f0 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e  nction passed in
2f900 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f910 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2f920 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2f930 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68  s in UTF-8 if th
2f940 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
2f950 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73         was regis
2f960 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
2f970 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2f980 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  eeded()] and.** 
2f990 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55           is in U
2f9a0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2f9b0 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63  e order if the c
2f9c0 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20  allback was.**  
2f9d0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2f9e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2f9f0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2fa00 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a  ed16()]..**.** .
2fa10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2fa20 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2fa30 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2fa40 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
2fa50 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2fa60 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2fa70 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
2fa80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2fa90 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
2faa0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2fab0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
2fac0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2fad0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2fae0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2faf0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2fb00 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2fb10 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2fb20 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2fb30 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2fb40 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2fb50 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2fb60 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2fb70 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2fb80 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2fb90 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2fba0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2fbb0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2fbc0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2fbd0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2fbe0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2fbf0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2fc00 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2fc10 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2fc20 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2fc30 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2fc40 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2fc50 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2fc60 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2fc70 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2fc80 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2fc90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2fca0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2fcb0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2fcc0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2fcd0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2fce0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2fcf0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2fd00 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2fd10 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2fd20 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2fd30 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2fd40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2fd50 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2fd60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2fd70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2fd80 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2fd90 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2fda0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2fdb0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2fdc0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2fdd0 43 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65  CAPI3REF:  Suspe
2fde0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
2fdf0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46   A Short Time {F
2fe00 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10530}.**.** The
2fe10 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2fe20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75   function.** cau
2fe30 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2fe40 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2fe50 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2fe60 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2fe70 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2fe80 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2fe90 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2fea0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
2feb0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
2fec0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
2fed0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
2fee0 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  ith .** millisec
2fef0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2ff00 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2ff10 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2ff20 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65  ed up to .** the
2ff30 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
2ff40 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
2ff50 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2ff60 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a  leep actually .*
2ff70 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
2ff80 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2ff90 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
2ffa0 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  d..**.** SQLite 
2ffb0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2ffc0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2ffd0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2ffe0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2fff0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
30000 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
30010 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
30020 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33  S:.**.** {F10533
30030 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
30040 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
30050 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  ce invokes the x
30060 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20  Sleep.**        
30070 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20    method of the 
30080 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
30090 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64  _vfs|VFS] in ord
300a0 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
300b0 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74    suspend execut
300c0 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
300d0 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74  nt thread for at
300e0 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20   least.**       
300f0 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64     M millisecond
30100 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36  s..**.** {F10536
30110 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
30120 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
30130 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
30140 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
30150 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64       millisecond
30160 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
30170 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66  lly requested of
30180 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a   the operating.*
30190 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65  *          syste
301a0 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  m, which might b
301b0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
301c0 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a  e parameter M..*
301d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
301e0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
301f0 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65   CAPI3REF:  Name
30200 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
30210 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
30220 20 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a   Files {F10310}.
30230 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
30240 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
30250 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
30260 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
30270 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
30280 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
30290 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
302a0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
302b0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
302c0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
302d0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
302e0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
302f0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
30300 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  .** is NULL poin
30310 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
30320 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66   does a search f
30330 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
30340 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66  e temporary.** f
30350 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
30360 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
30370 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
30380 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
30390 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
303a0 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65  ection.** has be
303b0 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69  en opened.  It i
303c0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
303d0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
303e0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
303f0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
30400 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
30410 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
30420 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
30430 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
30440 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65  been call and re
30450 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74  main unchanged t
30460 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51  hereafter..*/.SQ
30470 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
30480 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
30490 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
304a0 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74   CAPI3REF:  Test
304b0 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44   To See If The D
304c0 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75  atabase Is In Au
304d0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
304e0 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12930}.**.** Th
304f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
30500 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
30510 66 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e 6f  faces returns no
30520 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
30530 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
30540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30550 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
30560 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
30570 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
30580 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69  ely.   Autocommi
30590 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20  t mode is on.** 
305a0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74  by default.  Aut
305b0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
305c0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
305d0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
305e0 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
305f0 6f 64 65 20 69 73 20 72 65 65 6e 61 62 6c 65 64  ode is reenabled
30600 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
30610 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
30620 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
30630 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
30640 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
30650 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
30660 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
30670 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72  transactions (er
30680 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
30690 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
306a0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a  QLITE_IOERR], .*
306b0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
306c0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
306d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
306e0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
306f0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
30700 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
30710 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
30720 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
30730 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
30740 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f  t if SQLite auto
30750 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
30760 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
30770 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
30780 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
30790 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
307a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
307b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31  S:.**.** {F12931
307c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
307d0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29  et_autocommit(D)
307e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
307f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
30800 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
30810 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   if the [databas
30820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
30830 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
30840 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20  autocommit.**   
30850 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73         mode, res
30860 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
30870 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f   {F12932} Autoco
30880 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
30890 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
308a0 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63  * {F12933} Autoc
308b0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
308c0 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  sabled by a succ
308d0 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73  essful [BEGIN] s
308e0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
308f0 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d  {F12934} Autocom
30900 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  mit mode is enab
30910 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
30920 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  ful [COMMIT] or 
30930 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20  [ROLLBACK].**   
30940 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
30950 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ..** .**.** LIMI
30960 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20  TATIONS:.***.** 
30970 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {U12936} If anot
30980 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
30990 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
309a0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
309b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
309c0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
309d0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
309e0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
309f0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
30a00 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
30a10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
30a20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
30a30 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
30a40 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
30a50 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
30a60 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
30a70 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
30a80 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31   Statement {F131
30a90 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20}.**.** The sq
30aa0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
30ab0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
30ac0 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65  urns the [sqlite
30ad0 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
30ae0 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
30af0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30b00 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
30b10 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  ** The database 
30b20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20  handle returned 
30b30 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
30b40 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73  ndle.** is the s
30b50 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
30b60 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
30b70 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
30b80 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
30b90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
30ba0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
30bb0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
30bc0 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
30bd0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
30be0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
30bf0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
30c00 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54  **.** {F13123} T
30c10 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68  he [sqlite3_db_h
30c20 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66  andle(S)] interf
30c30 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
30c40 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
30c50 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61    to the [databa
30c60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
30c70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
30c80 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
30c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30ca0 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  S..*/.sqlite3 *s
30cb0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
30cc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
30cd0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
30ce0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
30cf0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
30d00 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
30d10 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12950}.**.** The
30d20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
30d30 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
30d40 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
30d50 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
30d60 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
30d70 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
30d80 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
30d90 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
30da0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
30db0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
30dc0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30dd0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
30de0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
30df0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
30e00 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
30e10 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
30e20 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
30e30 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
30e40 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
30e50 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
30e60 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
30e70 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
30e80 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
30e90 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
30ea0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
30eb0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
30ec0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
30ed0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
30ee0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
30ef0 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
30f00 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
30f10 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
30f20 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
30f30 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  k.  If the callb
30f40 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
30f50 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  hook function .*
30f60 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
30f70 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ro, then the com
30f80 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
30f90 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
30fa0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
30fb0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
30fc0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
30fd0 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
30fe0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
30ff0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
31000 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
31010 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  d..**.** Registe
31020 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
31030 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
31040 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
31050 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
31060 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
31070 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
31080 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
31090 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  en .** rolled ba
310a0 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
310b0 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
310c0 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
310d0 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
310e0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
310f0 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
31100 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
31110 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
31120 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
31130 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
31140 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
31150 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
31160 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
31170 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
31180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31190 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
311a0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
311b0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
311c0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
311d0 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
311e0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
311f0 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
31200 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
31210 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
31220 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
31230 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  o>.**.** These a
31240 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  re experimental 
31250 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61  interfaces and a
31260 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
31270 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ange..**.** INVA
31280 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
31290 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  12951} The [sqli
312a0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
312b0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
312c0 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
312d0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
312e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
312f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
31300 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
31310 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
31320 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
31330 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74   commits on [dat
31340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31350 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
31360 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  52} The [sqlite3
31370 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
31380 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
31390 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
313a0 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
313b0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
313c0 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
313d0 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20  e same .**      
313e0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
313f0 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f  nnection ] D , o
31400 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
31410 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  rst call.**     
31420 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69       for a parti
31430 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20  cular [database 
31440 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
31450 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61  *.** {F12953} Ea
31460 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
31470 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
31480 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
31490 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
314a0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
314b0 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
314c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d  ..**.** {F12954}
314d0 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
314e0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
314f0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
31500 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
31510 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
31520 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
31530 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65  back is cancelle
31540 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
31550 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
31560 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
31570 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
31580 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  its..**.** {F129
31590 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69  55} If the commi
315a0 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  t callback retur
315b0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e  ns non-zero then
315c0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a   the commit is.*
315d0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65  *          conve
315e0 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
315f0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
31600 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  961} The [sqlite
31610 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
31620 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
31630 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
31640 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
31650 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
31660 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
31670 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
31680 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
31690 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
316a0 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b   rolls back on [
316b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
316c0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
316d0 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69  12962} The [sqli
316e0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
316f0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
31700 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
31710 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
31720 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
31730 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
31740 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  th the same .** 
31750 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
31760 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20  se connection ] 
31770 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74  D , or NULL on t
31780 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
31790 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
317a0 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61  particular [data
317b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
317c0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36   D..**.** {F1296
317d0 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
317e0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
317f0 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  k_hook()] overwr
31800 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
31810 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  k.**          re
31820 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f  gistered by prio
31830 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  r calls..**.** {
31840 46 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46  F12964} If the F
31850 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
31860 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
31870 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e  ook(D,F,P)] is N
31880 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
31890 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63  then the rollbac
318a0 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  k hook callback 
318b0 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64  is cancelled and
318c0 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
318d0 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
318e0 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
318f0 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63  action rolls bac
31900 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  k..*/.void *sqli
31910 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
31920 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
31930 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
31940 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
31950 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
31960 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
31970 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
31980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31990 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
319a0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
319b0 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a  cks {F12970}.**.
319c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
319d0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
319e0 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74  erface.** regist
319f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
31a00 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
31a10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31a20 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20  tion identified 
31a30 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74  by the .** first
31a40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20   argument to be 
31a50 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
31a60 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
31a70 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
31a80 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  eleted..** Any c
31a90 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
31aa0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
31ab0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
31ac0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a  for the same .**
31ad0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31ae0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
31af0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
31b00 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
31b10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31b20 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
31b30 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20  voke when a .** 
31b40 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
31b50 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
31b60 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72  ted. .** The fir
31b70 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
31b80 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a  he callback is.*
31b90 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  * a copy of the 
31ba0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
31bb0 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
31bc0 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
31bd0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
31be0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
31bf0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
31c00 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
31c10 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49  DELETE] or [SQLI
31c20 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64  TE_UPDATE],.** d
31c30 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
31c40 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
31c50 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
31c60 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ck to be invoked
31c70 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  ..** The third a
31c80 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  nd .** fourth ar
31c90 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
31ca0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
31cb0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
31cc0 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a  database and .**
31cd0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
31ce0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
31cf0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
31d00 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
31d10 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20  arameter is .** 
31d20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
31d30 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20   row..** In the 
31d40 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
31d50 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72  e, this is the r
31d60 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74  owid after .** t
31d70 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
31d80 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  place..**.** The
31d90 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
31da0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
31db0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
31dc0 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
31dd0 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
31de0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
31df0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
31e00 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
31e10 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
31e20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
31e30 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20  tered, its pArg 
31e40 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75  value.** is retu
31e50 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
31e60 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
31e70 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
31e80 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
31e90 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
31ea0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
31eb0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,P)] interface c
31ec0 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  auses callback.*
31ed0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
31ee0 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f  ion F to be invo
31ef0 6b 65 64 20 77 69 74 68 20 66 69 72 73 74 20 70  ked with first p
31f00 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65  arameter P whene
31f10 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
31f20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d  a table row is m
31f30 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65  odified, inserte
31f40 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e  d, or deleted on
31f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
31f60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31f70 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
31f80 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  973} The [sqlite
31f90 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
31fa0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
31fb0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
31fc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
31fd0 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 69   P for the previ
31fe0 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20  ous call on the 
31ff0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
32000 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a  onnection] D,.**
32010 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
32020 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  L for the first 
32030 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  call..**.** {F12
32040 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 61  975} If the upda
32050 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  te hook callback
32060 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75   F in [sqlite3_u
32070 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
32080 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
32090 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
320a0 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61  no update callba
320b0 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a  cks are made..**
320c0 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 63  .** {F12977} Eac
320d0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
320e0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
320f0 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73  ,F,P)] overrides
32100 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20   prior calls.** 
32110 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
32120 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f  same interface o
32130 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
32140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32150 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37   D..**.** {F1297
32160 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  9} The update ho
32170 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ok callback is n
32180 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
32190 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a  internal system.
321a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 6c  **          tabl
321b0 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74  es such as sqlit
321c0 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
321d0 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65  ite_sequence are
321e0 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
321f0 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73 65   {F12981} The se
32200 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
32210 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c  o the update cal
32220 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20  lback .**       
32230 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51     is one of [SQ
32240 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
32250 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
32260 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
32270 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  ,.**          de
32280 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
32290 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
322a0 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
322b0 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
322c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20  .**.** {F12983} 
322d0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
322e0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
322f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
32300 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a  ontain pointers.
32310 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a  **          to z
32320 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
32330 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69  TF-8 strings whi
32340 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73  ch are the names
32350 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
32360 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64      database and
32370 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62   table that is b
32380 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a  eing updated...*
32390 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66  * {F12985} The f
323a0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
323b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72  rameter is the r
323c0 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20  owid of the row 
323d0 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  after.**        
323e0 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63    the change occ
323f0 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  urs..*/.void *sq
32400 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
32410 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
32420 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
32430 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
32440 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
32450 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
32460 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
32470 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61  * CAPI3REF:  Ena
32480 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
32490 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
324a0 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a  e {F10330}.**.**
324b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
324c0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
324d0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
324e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
324f0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
32500 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
32510 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63  s between connec
32520 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d  tions to the sam
32530 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53  e database..** S
32540 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
32550 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
32560 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64 69  t is true and di
32570 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
32580 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c  gument.** is fal
32590 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20  se..**.** Cache 
325a0 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
325b0 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a  ed and disabled.
325c0 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ** for an entire
325d0 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20   process. {END} 
325e0 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65  This is a change
325f0 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   as of SQLite ve
32600 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20  rsion 3.5.0..** 
32610 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
32620 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61  s of SQLite, sha
32630 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ring was.** enab
32640 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
32650 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
32660 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
32670 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
32680 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
32690 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
326a0 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
326b0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
326c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
326d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
326e0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
326f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
32700 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
32710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32720 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
32730 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
32740 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
32750 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
32760 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
32770 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
32780 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
32790 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
327a0 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 20 57  hared cache.   W
327b0 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  hen shared.** ca
327c0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  che is enabled, 
327d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
327e0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50  ate_module()] AP
327f0 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  I used to regist
32800 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  er.** virtual ta
32810 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73  bles will always
32820 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
32830 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
32840 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
32850 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
32860 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20  ed cache was.** 
32870 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
32880 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  led successfully
32890 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
328a0 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  e].** is returne
328b0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  d otherwise..**.
328c0 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20  ** Shared cache 
328d0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
328e0 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
328f0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
32900 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
32910 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
32920 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
32930 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
32940 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
32950 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
32960 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
32970 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
32980 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d  .** .** {F10331}
32990 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
329a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
329b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
329c0 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20  ed_cache(B)].** 
329d0 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e           will en
329e0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
329f0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
32a00 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71  e for any subseq
32a10 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  uently.**       
32a20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61     created [data
32a30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32a40 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f   in the same pro
32a50 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  cess..**.** {F10
32a60 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64  336} When shared
32a70 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
32a80 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
32a90 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
32aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
32ab0 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61  erface will alwa
32ac0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
32ad0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33  or..**.** {F1033
32ae0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
32af0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
32b00 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63  che(B)] interfac
32b10 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
32b20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
32b30 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
32b40 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
32b50 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
32b60 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sfully..**.** {F
32b70 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61  10339} Shared ca
32b80 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
32b90 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69  by default..*/.i
32ba0 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
32bb0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
32bc0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32bd0 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54  3REF:  Attempt T
32be0 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
32bf0 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a  ry {F17340}.**.*
32c00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
32c10 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
32c20 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
32c30 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62  s to.** free N b
32c40 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d  ytes of heap mem
32c50 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
32c60 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
32c70 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  l memory.** allo
32c80 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20  cations held by 
32c90 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 62  the database lab
32ca0 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d  rary. {END}  Mem
32cb0 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63  ory used.** to c
32cc0 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61  ache database pa
32cd0 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
32ce0 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
32cf0 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e   example of.** n
32d00 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
32d10 6f 72 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 65  ory.  Sqlite3_re
32d20 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
32d30 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
32d40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
32d50 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68  tually freed, wh
32d60 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
32d70 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61  e or less.** tha
32d80 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
32d90 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  uested..**.** IN
32da0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
32db0 7b 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71  {F17341} The [sq
32dc0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32dd0 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61  mory(N)] interfa
32de0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a  ce attempts to.*
32df0 2a 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20  *          free 
32e00 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
32e10 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
32e20 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
32e30 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tial.**         
32e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
32e50 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20  ons held by the 
32e60 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 79  database labrary
32e70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d  ..**.** {F16342}
32e80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32e90 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d  lease_memory(N)]
32ea0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32eb0 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
32ec0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
32ed0 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d  y freed, which m
32ee0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
32ef0 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
32f00 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
32f10 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69   requested..*/.i
32f20 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
32f30 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
32f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32f50 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74    Impose A Limit
32f60 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46   On Heap Size {F
32f70 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17350}.**.** The
32f80 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
32f90 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
32fa0 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61  face.** places a
32fb0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e   "soft" limit on
32fc0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
32fd0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
32fe0 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
32ff0 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 49  .** by SQLite. I
33000 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
33010 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
33020 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77  ested .** that w
33030 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 20  ould exceed the 
33040 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
33050 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
33060 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a  e_memory()] is.*
33070 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  * invoked one or
33080 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
33090 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
330a0 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
330b0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61  ocation.** is ma
330c0 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  de..**.** The li
330d0 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
330e0 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66  oft", because if
330f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
33100 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63  ease_memory()] c
33110 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75  annot.** free su
33120 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
33130 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
33140 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
33150 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
33160 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
33170 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
33180 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
33190 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
331a0 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  **.** A negative
331b0 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
331c0 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
331d0 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
331e0 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
331f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
33200 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
33210 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
33220 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
33230 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54   exhausted..** T
33240 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
33250 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
33260 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
33270 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
33280 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
33290 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
332a0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
332b0 20 20 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65    .** But if the
332c0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
332d0 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c   cannot honored,
332e0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
332f0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
33300 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
33310 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
33320 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
33330 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  t is .** called 
33340 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
33350 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
33360 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
33370 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
33380 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
33390 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
333a0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
333b0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
333c0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
333d0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
333e0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
333f0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
33400 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
33410 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
33420 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
33430 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
33440 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
33450 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
33460 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
33470 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
33480 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
33490 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
334a0 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
334b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
334c0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
334d0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
334e0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
334f0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
33500 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
33510 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
33520 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
33530 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
33540 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20  .**.** {F16351} 
33550 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  The [sqlite3_sof
33560 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d  t_heap_limit(N)]
33570 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65   interface place
33580 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a  s a soft limit.*
33590 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20  *          of N 
335a0 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f  bytes on the amo
335b0 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
335c0 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
335d0 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20  llocated.**     
335e0 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69       using [sqli
335f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
33600 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
33610 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e  c()] at any poin
33620 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
33630 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   time..**.** {F1
33640 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20  6352} If a call 
33650 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
33660 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
33670 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75  3_realloc()] wou
33680 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ld.**          c
33690 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61  ause the total a
336a0 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74  mount of allocat
336b0 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63  ed memory to exc
336c0 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  eed the.**      
336d0 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69      soft heap li
336e0 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  mit, then [sqlit
336f0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
33700 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  y()] is invoked.
33710 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
33720 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64  n attempt to red
33730 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75  uce the memory u
33740 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72  sage prior to pr
33750 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20  oceeding.**     
33760 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 65       with the me
33770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33780 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b  attempt..**.** {
33790 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f  F16353} Calls to
337a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
337b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
337c0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
337d0 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 20  trigger.**      
337e0 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20      attempts to 
337f0 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73  reduce memory us
33800 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 20  age through the 
33810 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
33820 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63 68  **          mech
33830 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65  anism continue e
33840 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 65 6d  ven if the attem
33850 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d  pt to reduce mem
33860 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
33870 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 63 65  usage is unsucce
33880 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssful..**.** {F1
33890 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76 65  6354} A negative
338a0 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
338b0 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74  or N in a call t
338c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
338d0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
338e0 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73  _limit(N)] means
338f0 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
33900 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20  o soft.**       
33910 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e     heap limit an
33920 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  d [sqlite3_relea
33930 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
33940 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20  l only be.**    
33950 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68 65        called whe
33960 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70  n memory is comp
33970 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 65 64  letely exhausted
33980 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d  ..**.** {F16355}
33990 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
339a0 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ue for the soft 
339b0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65  heap limit is ze
339c0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  ro..**.** {F1635
339d0 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  8} Each call to 
339e0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
339f0 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65  ap_limit(N)] ove
33a00 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20  rrides the.**   
33a10 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 73 65         values se
33a20 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 63  t by all prior c
33a30 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  alls..*/.void sq
33a40 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
33a50 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  limit(int);../*.
33a60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78  ** CAPI3REF:  Ex
33a70 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
33a80 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
33a90 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30   A Table {F12850
33aa0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
33ab0 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tine.** returns 
33ac0 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20  meta-data about 
33ad0 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
33ae0 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20  n of a specific 
33af0 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
33b00 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
33b10 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
33b20 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20  n handle passed 
33b30 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
33b40 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65  ction .** argume
33b50 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  nt..**.** The co
33b60 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
33b70 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
33b80 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
33b90 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
33ba0 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69   .** this functi
33bb0 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  on. The second p
33bc0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
33bd0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
33be0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
33bf0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
33c00 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68  mp" or an attach
33c10 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
33c20 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
33c30 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
33c40 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73  r NULL. If it is
33c50 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
33c60 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
33c70 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
33c80 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
33c90 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
33ca0 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65  algorithm as the
33cb0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
33cc0 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73   uses to .** res
33cd0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
33ce0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
33cf0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
33d00 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
33d10 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
33d20 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
33d30 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
33d40 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  mn .** name of t
33d50 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
33d60 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
33d70 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
33d80 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a  e parameters .**
33d90 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
33da0 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61  .** Meta informa
33db0 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  tion is returned
33dc0 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
33dd0 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
33de0 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  ons passed as.**
33df0 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62   the 5th and sub
33e00 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
33e10 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
33e20 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
33e30 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  e .** arguments 
33e40 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20  may be NULL, in 
33e50 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
33e60 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
33e70 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a  ment of meta .**
33e80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
33e90 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommitted..**.** 
33ea0 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
33eb0 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
33ec0 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
33ed0 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
33ee0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33ef0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a  ----------.**.**
33f00 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
33f10 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
33f20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
33f30 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
33f40 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
33f50 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
33f60 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33f70 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
33f80 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
33f90 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
33fa0 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
33fb0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
33fc0 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
33fd0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
33fe0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
33ff0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
34000 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
34010 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
34020 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
34030 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
34040 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
34050 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
34060 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
34070 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
34080 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
34090 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
340a0 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
340b0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
340c0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
340d0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
340e0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
340f0 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
34100 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
34110 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
34120 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
34130 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
34140 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
34150 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
34160 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
34170 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
34180 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
34190 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
341a0 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
341b0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
341c0 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
341d0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
341e0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
341f0 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
34200 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
34210 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
34220 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
34230 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
34240 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
34250 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
34260 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
34270 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
34280 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
34290 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
342a0 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
342b0 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
342c0 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
342d0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
342e0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
342f0 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
34300 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
34310 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
34320 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
34330 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
34340 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
34350 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
34360 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
34370 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
34380 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
34390 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
343a0 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
343b0 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
343c0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
343d0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
343e0 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
343f0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
34400 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
34410 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
34420 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
34430 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
34440 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
34450 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
34460 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
34470 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
34480 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
34490 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
344a0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
344b0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
344c0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
344d0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
344e0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
344f0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
34500 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34520 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
34530 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
34540 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
34550 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34560 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
34570 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
34580 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
34590 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
345a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
345b0 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
345c0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
345d0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
345e0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
345f0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
34600 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
34610 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
34620 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
34630 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
34640 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
34650 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
34660 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
34670 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
34680 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
34690 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
346a0 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
346b0 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
346c0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
346d0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
346e0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
346f0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
34700 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
34710 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
34720 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
34730 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
34740 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
34750 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
34760 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  600}.**.** {F126
34770 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
34780 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
34790 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74   interface.** at
347a0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
347b0 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
347c0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
347d0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
347e0 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36  .** zFile. {F126
347f0 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f  02} The entry po
34800 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46  int is zProc. {F
34810 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
34820 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63   be 0.** in whic
34830 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
34840 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
34850 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74  nt defaults.** t
34860 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
34870 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
34880 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73  * {F12604} The s
34890 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
348a0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
348b0 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72  e shall.** retur
348c0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
348d0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
348e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
348f0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
34900 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ong..**.** {F126
34910 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  05}.** If an err
34920 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
34930 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
34940 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c   then the.** sql
34950 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
34960 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
34970 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
34980 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
34990 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
349a0 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
349b0 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ed in memory obt
349c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
349d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
349e0 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c  * {END}  The cal
349f0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
34a00 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
34a10 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
34a20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
34a30 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
34a40 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  606}.** Extensio
34a50 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
34a60 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
34a70 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
34a80 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
34a90 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
34aa0 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
34ab0 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
34ac0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
34ad0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
34ae0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
34af0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
34b00 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
34b10 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
34b20 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
34b30 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
34b40 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
34b50 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
34b60 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
34b70 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
34b80 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
34b90 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
34ba0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
34bb0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
34bc0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
34bd0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
34be0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
34bf0 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
34c00 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
34c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
34c20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
34c30 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
34c40 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a  ing {F12620}.**.
34c50 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
34c60 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
34c70 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
34c80 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
34c90 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
34ca0 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
34cb0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
34cc0 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
34cd0 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
34ce0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
34cf0 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
34d00 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
34d10 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
34d20 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
34d30 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
34d40 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
34d50 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
34d60 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
34d70 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20   off.  {F12622} 
34d80 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
34d90 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20  ault. {END} See 
34da0 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
34db0 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c  .** {F12621} Cal
34dc0 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
34dd0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
34de0 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  ion() routine.**
34df0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
34e00 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
34e10 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
34e20 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
34e30 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
34e40 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
34e50 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  in. {END}.*/.int
34e60 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
34e70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
34e80 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
34e90 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
34ea0 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72  API3REF: Make Ar
34eb0 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75  rangements To Au
34ec0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
34ed0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
34ee0 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12640}.**.** {F1
34ef0 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
34f00 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ion.** registers
34f10 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
34f20 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
34f30 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
34f40 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65  invoked.** whene
34f50 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  ver a new databa
34f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34f70 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a   opened using.**
34f80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
34f90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
34fa0 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
34fb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b  e3_open_v2()]. {
34fc0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
34fd0 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
34fe0 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
34ff0 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
35000 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
35010 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
35020 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
35030 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
35040 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
35050 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61   to all new data
35060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
35070 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d  ..**.** {F12642}
35080 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
35090 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
350a0 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
350b0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
350c0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
350d0 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
350e0 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
350f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d  ..**.** {F12643}
35100 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
35110 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
35120 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
35130 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
35140 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
35150 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c  from sqlite_mall
35160 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79  oc(). {END} If y
35170 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20  ou run a memory 
35180 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20  leak.** checker 
35190 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20  on your program 
351a0 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61  and it reports a
351b0 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66   leak because of
351c0 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20   this.** array, 
351d0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  then invoke [sql
351e0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
351f0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
35200 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77  or.** to shutdow
35210 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
35220 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  mory..**.** {F12
35230 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
35240 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
35250 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
35260 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ds. {END}.**.** 
35270 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
35280 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
35290 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
352a0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
352b0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
352c0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
352d0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
352e0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
352f0 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f  n(void *xEntryPo
35300 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  int);.../*.** CA
35310 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
35320 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
35330 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36  n Loading {F1266
35340 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31  0}.**.** {F12661
35350 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
35360 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
35370 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
35380 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  ed.** automatic 
35390 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44  extensions. {END
353a0 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  }  This.** routi
353b0 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
353c0 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
353d0 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  r [sqlite3_auto_
353e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
353f0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
35400 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20  2662} This call 
35410 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74  disabled automat
35420 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
35430 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45   all threads. {E
35440 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ND}.**.** This i
35450 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
35460 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
35470 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
35480 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
35490 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
354a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
354b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
354c0 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
354d0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a  on(void);.../*.*
354e0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
354f0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
35500 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
35510 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
35520 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
35530 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
35540 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
35550 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
35560 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
35570 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
35580 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
35590 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
355a0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
355b0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
355c0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
355d0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
355e0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
355f0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
35600 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
35610 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
35620 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65  chanism stablize
35630 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
35640 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
35650 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
35660 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
35670 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
35680 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
35690 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
356a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
356b0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
356c0 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
356d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
356e0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
356f0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
35700 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
35710 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
35720 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
35730 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35740 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
35750 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
35760 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35770 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
35780 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
35790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
357a0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
357b0 6a 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a 2a  ject {F18000}.**
357c0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
357d0 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20  e3_module.**.** 
357e0 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c  A module is a cl
357f0 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74  ass of virtual t
35800 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64  ables.  Each mod
35810 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a  ule is defined.*
35820 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65  * by an instance
35830 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
35840 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  g structure.  Th
35850 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
35860 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20  sists.** mostly 
35870 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
35880 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74  he module..*/.st
35890 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
358a0 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
358b0 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
358c0 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
358d0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
358e0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
358f0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
35900 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
35910 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
35920 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
35930 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
35940 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
35950 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
35960 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
35970 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
35980 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
35990 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
359a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
359b0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
359c0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
359d0 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
359e0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
359f0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
35a00 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
35a10 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
35a20 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
35a30 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
35a40 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35a50 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35a60 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
35a70 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
35a80 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
35a90 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
35aa0 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
35ab0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35ac0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
35ad0 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
35ae0 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
35af0 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
35b00 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
35b10 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
35b20 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
35b30 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
35b40 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
35b50 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
35b60 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
35b70 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
35b80 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
35b90 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
35ba0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
35bb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35bc0 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
35bd0 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
35be0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
35bf0 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
35c00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
35c10 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
35c20 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
35c30 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
35c40 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
35c50 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
35c60 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
35c70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
35c80 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35c90 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35ca0 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
35cb0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
35cc0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
35cd0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35ce0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35cf0 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
35d00 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
35d10 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
35d20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
35d30 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35d40 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
35d50 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
35d60 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35d70 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35d80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35d90 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
35da0 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52  rg);..  int (*xR
35db0 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  ename)(sqlite3_v
35dc0 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73  tab *pVtab, cons
35dd0 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d  t char *zNew);.}
35de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35df0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
35e00 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d   Indexing Inform
35e10 61 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a 2a  ation {F18100}.*
35e20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
35e30 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
35e40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35e50 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
35e60 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
35e70 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
35e80 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
35e90 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
35ea0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
35eb0 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78  reply from the x
35ec0 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74  BestIndex.** met
35ed0 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  hod of an sqlite
35ee0 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66  3_module.  The f
35ef0 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
35f00 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
35f10 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
35f20 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
35f30 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
35f40 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
35f50 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
35f60 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
35f70 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
35f80 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
35f90 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
35fa0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
35fb0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a  straints of the.
35fc0 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20  ** form:.**.**  
35fd0 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50         column OP
35fe0 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72   expr.**.** Wher
35ff0 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
36000 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
36010 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65   &gt;=.  .** The
36020 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
36030 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a  ator is stored.*
36040 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  * in aConstraint
36050 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65  [].op.  The inde
36060 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
36070 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a  is stored in .**
36080 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
36090 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
360a0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
360b0 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
360c0 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
360d0 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
360e0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
360f0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
36100 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
36110 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
36120 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
36130 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
36140 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
36150 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
36160 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
36170 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
36180 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
36190 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
361a0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
361b0 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
361c0 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
361d0 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
361e0 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
361f0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
36200 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
36210 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
36220 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
36230 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
36240 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
36250 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
36260 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
36270 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
36280 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
36290 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
362a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
362b0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
362c0 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
362d0 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
362e0 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
362f0 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
36300 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
36310 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
36320 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  ** The xBestInde
36330 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  x method must fi
36340 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
36350 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
36360 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
36370 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
36380 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
36390 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65  er.  If argvInde
363a0 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
363b0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
363c0 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
363d0 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
363e0 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
363f0 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
36400 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
36410 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
36420 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
36430 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
36440 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
36450 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
36460 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
36470 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
36480 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
36490 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
364a0 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
364b0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
364c0 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
364d0 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
364e0 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
364f0 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a   into xFilter..*
36500 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  * sqlite3_free()
36510 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
36520 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54   idxPtr if needT
36530 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
36540 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  rue..**.** The o
36550 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
36560 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
36570 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69   from xFilter wi
36580 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
36590 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
365a0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
365b0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
365c0 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
365d0 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
365e0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
365f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d  .**.** The estim
36600 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
36610 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
36620 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
36630 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
36640 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
36650 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
36660 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
36670 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
36680 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
36690 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
366a0 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
366b0 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
366c0 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
366d0 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
366e0 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
366f0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36700 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
36710 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
36720 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
36730 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
36740 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
36750 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
36760 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
36770 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
36780 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
36790 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
367a0 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
367b0 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
367c0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
367d0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
367e0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
367f0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
36800 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
36810 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
36820 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
36830 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
36840 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
36850 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
36860 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
36870 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
36880 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
36890 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
368a0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
368b0 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
368c0 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
368d0 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
368e0 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
368f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
36900 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
36910 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
36920 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
36930 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36940 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
36950 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
36960 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
36970 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
36980 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
36990 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
369a0 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
369b0 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
369c0 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
369d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
369e0 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
369f0 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75  ause */..  /* Ou
36a00 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
36a10 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36a20 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
36a30 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
36a40 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
36a50 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
36a60 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
36a70 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
36a80 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
36a90 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
36aa0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
36ab0 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
36ac0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
36ad0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
36ae0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
36af0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
36b00 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
36b10 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
36b20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
36b30 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
36b40 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
36b50 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
36b60 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
36b70 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
36b80 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
36b90 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
36ba0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
36bb0 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
36bc0 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
36bd0 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
36be0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
36bf0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
36c00 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
36c10 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
36c20 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
36c30 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
36c40 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
36c50 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
36c60 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36c70 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
36c80 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36c90 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
36ca0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
36cb0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36cc0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
36cd0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36ce0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
36cf0 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
36d00 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36d10 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
36d20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
36d30 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
36d40 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
36d50 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
36d60 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
36d70 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   Implementation 
36d80 7b 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F18200}.**.** T
36d90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
36da0 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  sed to register 
36db0 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d  a new module nam
36dc0 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65  e with an SQLite
36dd0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
36de0 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
36df0 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
36e00 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67   before creating
36e10 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20   new.** virtual 
36e20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f  tables on the mo
36e30 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20  dule, or before 
36e40 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e  using preexistin
36e50 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  g virtual.** tab
36e60 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  les of the modul
36e70 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
36e80 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
36e90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36eb0 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
36ec0 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
36ed0 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
36ee0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
36ef0 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
36f00 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
36f10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
36f20 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20  te3_module *,   
36f30 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
36f40 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
36f50 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20  void *          
36f60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c             /* Cl
36f70 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
36f80 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
36f90 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
36fa0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
36fb0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
36fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46  mplementation {F
36fd0 31 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  18210}.**.** Thi
36fe0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
36ff0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71  ntical to the sq
37000 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
37010 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f  ule() method abo
37020 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ve,.** except th
37030 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64  at it allows a d
37040 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
37050 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69  on to be specifi
37060 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65  ed. It is.** eve
37070 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e  n more experimen
37080 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73  tal than the res
37090 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
370a0 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a   tables API..*/.
370b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
370c0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
370d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
370e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
370f0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
37100 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
37110 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
37120 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
37130 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
37140 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
37150 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
37160 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
37170 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
37180 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
37190 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
371a0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
371b0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
371c0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
371d0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
371e0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
371f0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
37200 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
37210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37220 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
37230 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b  nstance Object {
37240 46 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F18010}.** KEYWO
37250 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
37260 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  b.**.** Every mo
37270 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
37280 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
37290 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
372a0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
372b0 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  * to describe a 
372c0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
372d0 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  nce of the modul
372e0 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  e.  Each subclas
372f0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
37300 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
37310 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
37320 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
37330 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a  entation.   The.
37340 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  ** purpose of th
37350 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
37360 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
37370 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
37380 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20  re common.** to 
37390 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
373a0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
373b0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
373c0 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74   methods can set
373d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
373e0 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61  e by assigning a
373f0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69  .** string obtai
37400 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
37410 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45  _mprintf() to zE
37420 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
37430 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
37440 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
37450 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
37460 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
37470 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
37480 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ).** prior to as
37490 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
374a0 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
374b0 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f    After the erro
374c0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20  r message.** is 
374d0 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20  delivered up to 
374e0 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69  the client appli
374f0 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69  cation, the stri
37500 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ng will be autom
37510 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65  atically.** free
37520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65  d by sqlite3_fre
37530 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72  e() and the zErr
37540 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62  Msg field will b
37550 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a  e zeroed.  Note.
37560 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  ** that sqlite3_
37570 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
37580 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65  lite3_free() are
37590 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72   used on the zEr
375a0 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69  rMsg field.** si
375b0 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nce virtual tabl
375c0 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20  es are commonly 
375d0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c  implemented in l
375e0 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
375f0 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e  ns which.** do n
37600 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74  ot have access t
37610 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66  o sqlite3MPrintf
37620 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65  () or sqlite3Fre
37630 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  e()..*/.struct s
37640 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
37650 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
37660 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
37670 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
37680 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
37690 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
376a0 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
376b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
376c0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a  d internally */.
376d0 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
376e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
376f0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
37700 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
37710 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
37720 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
37730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37740 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
37750 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
37760 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
37770 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
37780 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
37790 20 4f 62 6a 65 63 74 20 20 7b 46 31 38 30 32 30   Object  {F18020
377a0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  }.** KEYWORDS: s
377b0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
377c0 6f 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d  or.**.** Every m
377d0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
377e0 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
377f0 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c  lass of the foll
37800 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a  owing structure.
37810 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  ** to describe c
37820 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
37830 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75  t into the virtu
37840 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65  al table and are
37850 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
37860 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
37870 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
37880 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
37890 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f   using the.** xO
378a0 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
378b0 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
378c0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
378d0 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e  ation will defin
378e0 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  e.** the content
378f0 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72   of a cursor str
37900 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69  ucture to suit i
37910 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a  ts own needs..**
37920 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c  .** This supercl
37930 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72  ass exists in or
37940 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69  der to define fi
37950 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73  elds of the curs
37960 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  or that.** are c
37970 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70  ommon to all imp
37980 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f  lementations..*/
37990 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
379a0 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20  vtab_cursor {.  
379b0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
379c0 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72  tab;      /* Vir
379d0 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68  tual table of th
379e0 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f  is cursor */.  /
379f0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
37a00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37a10 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
37a20 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
37a30 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
37a40 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
37a50 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f  are The Schema O
37a60 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  f A Virtual Tabl
37a70 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a 2a  e {F18280}.**.**
37a80 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64   The xCreate and
37a90 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
37aa0 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73  s of a module us
37ab0 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  e the following 
37ac0 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  API.** to declar
37ad0 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
37ae0 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
37af0 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
37b00 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
37b10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
37b20 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
37b30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
37b40 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
37b50 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
37b60 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a  *zCreateTable);.
37b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37b80 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
37b90 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
37ba0 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 33 30 30  al Table {F18300
37bb0 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  }.**.** Virtual 
37bc0 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69  tables can provi
37bd0 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69  de alternative i
37be0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37bf0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75  f functions.** u
37c00 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75  sing the xFindFu
37c10 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20  nction method.  
37c20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
37c30 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
37c40 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
37c50 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
37c60 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   be overloaded..
37c70 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d  **.** This API m
37c80 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62  akes sure a glob
37c90 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20  al version of a 
37ca0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
37cb0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61  particular.** na
37cc0 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66  me and number of
37cd0 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73   parameters exis
37ce0 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20  ts.  If no such 
37cf0 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a  function exists.
37d00 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41  ** before this A
37d10 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20  PI is called, a 
37d20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
37d30 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d  created.  The im
37d40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
37d50 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
37d60 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
37d70 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
37d80 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
37d90 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
37da0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
37db0 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
37dc0 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
37dd0 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
37de0 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68   to be a place-h
37df0 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
37e00 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
37e10 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74  oaded.** by virt
37e20 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a  ual tables..**.*
37e30 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c  * This API shoul
37e40 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20  d be considered 
37e50 70 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74  part of the virt
37e60 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
37e70 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73  ace,.** which is
37e80 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
37e90 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  d subject to cha
37ea0 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
37eb0 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e  te3_overload_fun
37ec0 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ction(sqlite3*, 
37ed0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
37ee0 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29  cName, int nArg)
37ef0 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
37f00 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
37f10 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
37f20 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62  anism defined ab
37f30 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20  ove (back up.** 
37f40 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d  to a comment rem
37f50 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20  arkably similar 
37f60 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20  to this one) is 
37f70 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
37f80 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
37f90 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
37fa0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
37fb0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
37fc0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
37fd0 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
37fe0 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
37ff0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
38000 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
38010 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
38020 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
38030 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
38040 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
38050 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
38060 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
38070 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
38080 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
38090 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
380a0 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  t..**.****** EXP
380b0 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
380c0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
380d0 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
380e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a  ***********.*/..
380f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38100 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
38110 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 30  pen BLOB {F17800
38120 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
38130 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
38140 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
38150 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
38160 69 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74  ich.** increment
38170 61 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20 70 72  al I/O can be pr
38180 65 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65  eformed..** Obje
38190 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
381a0 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 0a   are created by.
381b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
381c0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73  _open()] and des
381d0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
381e0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
381f0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
38200 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
38210 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
38220 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
38230 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
38240 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
38250 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
38260 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c  ctions of the bl
38270 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  ob..** The [sqli
38280 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
38290 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
382a0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
382b0 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62  the.** blob in b
382c0 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
382d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
382e0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
382f0 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
38300 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
38310 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
38320 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a  I/O {F17810}.**.
38330 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
38340 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c  es opens a handl
38350 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f  e to the blob lo
38360 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20  cated.** in row 
38370 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f  iRow, column zCo
38380 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62  lumn, table zTab
38390 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
383a0 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20  Db;.** in other 
383b0 77 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d 65  words,  the same
383c0 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64   blob that would
383d0 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
383e0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
383f0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
38400 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
38410 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d  le WHERE rowid =
38420 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
38430 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
38440 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
38450 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
38460 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65   the blob is ope
38470 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64  ned for .** read
38480 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73   and write acces
38490 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f  s. If it is zero
384a0 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70  , the blob is op
384b0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a  ened for read .*
384c0 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  * access..**.** 
384d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
384e0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
384f0 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
38500 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
38510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
38520 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
38530 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
38540 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
38550 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77  ** is assigned w
38560 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
38570 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73   is connected us
38580 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a  ing [ATTACH]..**
38590 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   For the main da
385a0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
385b0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
385c0 73 20 22 6d 61 69 6e 22 2e 20 20 46 6f 72 0a 2a  s "main".  For.*
385d0 2a 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74  * TEMP tables, t
385e0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
385f0 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a   is "temp"..**.*
38600 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
38610 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
38620 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
38630 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  w .** [sqlite3_b
38640 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
38650 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  e] is written to
38660 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f 74   *ppBlob. .** Ot
38670 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
38680 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
38690 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61  d and .** any va
386a0 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a  lue written to *
386b0 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f  ppBlob should no
386c0 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  t be used by the
386d0 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73   caller..** This
386e0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
386f0 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64  he database-hand
38700 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  le error code an
38710 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
38720 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
38730 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
38740 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
38750 6d 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49  msg()]..** .** I
38760 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
38770 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 63   {F17813} A succ
38780 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
38790 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
387a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c  3_blob_open(D,B,
387b0 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20  T,C,R,F,P)].**  
387c0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
387d0 65 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c 69  e opens an [sqli
387e0 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
387f0 20 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a 2a   P on the blob.*
38800 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 6f  *          in co
38810 6c 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65 20  lumn C of table 
38820 54 20 69 6e 20 64 61 74 61 62 61 73 65 20 42 20  T in database B 
38830 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
38840 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
38850 2a 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75 63  * {F17814} A suc
38860 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
38870 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62  on of [sqlite3_b
38880 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d  lob_open(D,...)]
38890 20 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20 20   starts.**      
388a0 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 61      a new transa
388b0 63 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62 61  ction on [databa
388c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
388d0 20 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63 74   if that connect
388e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
388f0 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69  is not already i
38900 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  n a transaction.
38910 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d 20  .**.** {F17816} 
38920 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
38930 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52  b_open(D,B,T,C,R
38940 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
38950 20 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62 0a   opens the blob.
38960 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
38970 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61  read and write a
38980 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c  ccess if and onl
38990 79 20 69 66 20 74