/ Hex Artifact Content
Login

Artifact b38a20988588df2467722d5e0be9a3e66bec7203:


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 34 34 20 32 30 30 38 2f  in,v 1.344 2008/
05f0: 30 36 2f 32 31 20 31 31 3a 32 30 3a 34 38 20 6d  06/21 11:20:48 m
0600: 69 68 61 69 6c 69 6d 20 45 78 70 20 24 0a 2a 2f  ihailim Exp $.*/
0610: 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45  .#ifndef _SQLITE
0620: 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51  3_H_.#define _SQ
0630: 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64  LITE3_H_.#includ
0640: 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20  e <stdarg.h>    
0650: 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74   /* Needed for t
0660: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66  he definition of
0670: 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a   va_list */../*.
0680: 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20  ** Make sure we 
0690: 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74  can call this st
06a0: 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f  uff from C++..*/
06b0: 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70  .#ifdef __cplusp
06c0: 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b  lus.extern "C" {
06d0: 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20  .#endif.../*.** 
06e0: 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20  Add the ability 
06f0: 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74  to override 'ext
0700: 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ern'.*/.#ifndef 
0710: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20  SQLITE_EXTERN.# 
0720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
0730: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64  TERN extern.#end
0740: 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65  if../*.** Ensure
0750: 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77   these symbols w
0760: 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20  ere not defined 
0770: 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73  by some previous
0780: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f   header file..*/
0790: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
07a0: 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53  ERSION.# undef S
07b0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65  QLITE_VERSION.#e
07c0: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49  ndif.#ifdef SQLI
07d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
07e0: 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  R.# undef SQLITE
07f0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
0800: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
0810: 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
0820: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
0830: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 46 31  sion Numbers {F1
0840: 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0010}.**.** The 
0850: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61  SQLITE_VERSION a
0860: 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  nd SQLITE_VERSIO
0870: 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65  N_NUMBER #define
0880: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69  s in.** the sqli
0890: 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69  te3.h file speci
08a0: 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f  fy the version o
08b0: 66 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68  f SQLite with wh
08c0: 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64  ich.** that head
08d0: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
08e0: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iated..**.** The
08f0: 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51   "version" of SQ
0900: 4c 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67  Lite is a string
0910: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e   of the form "X.
0920: 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72  Y.Z"..** The phr
0930: 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22  ase "alpha" or "
0940: 62 65 74 61 22 20 6d 69 67 68 74 20 62 65 20 61  beta" might be a
0950: 70 70 65 6e 64 65 64 20 61 66 74 65 72 20 74 68  ppended after th
0960: 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61  e Z..** The X va
0970: 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72  lue is major ver
0980: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61  sion number alwa
0990: 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e  ys 3 in SQLite3.
09a0: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20  .** The X value 
09b0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65  only changes whe
09c0: 6e 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  n backwards comp
09d0: 61 74 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20  atibility is.** 
09e0: 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e  broken and we in
09f0: 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72  tend to never br
0a00: 65 61 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f  eak backwards co
0a10: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
0a20: 54 68 65 20 59 20 76 61 6c 75 65 20 69 73 20 74  The Y value is t
0a30: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e  he minor version
0a40: 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79   number and only
0a50: 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a   changes when.**
0a60: 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72   there are major
0a70: 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65   feature enhance
0a80: 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66  ments that are f
0a90: 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  orwards compatib
0aa0: 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61  le.** but not ba
0ab0: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
0ac0: 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c  le..** The Z val
0ad0: 75 65 20 69 73 20 74 68 65 20 72 65 6c 65 61 73  ue is the releas
0ae0: 65 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20  e number and is 
0af0: 69 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68  incremented with
0b00: 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65  .** each release
0b10: 20 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b   but resets back
0b20: 20 74 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59   to 0 whenever Y
0b30: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e   is incremented.
0b40: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
0b50: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b60: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
0b70: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
0b80: 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a  number()]..**.**
0b90: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
0ba0: 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20  ** {F10011} The 
0bb0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23  SQLITE_VERSION #
0bc0: 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71  define in the sq
0bd0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66  lite3.h header f
0be0: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
0bf0: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0c00: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c10: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c20: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c30: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c40: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c50: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c60: 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68  *.** {F10014} Th
0c70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c80: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0c90: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
0ca0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0cb0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0cc0: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0cd0: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0ce0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0cf0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0d00: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0d10: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0d20: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0d30: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
0d40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
0d50: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
0d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
0d80: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
0d90: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
0da0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
0db0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
0dc0: 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 20  ers {F10020}.** 
0dd0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
0de0: 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  3_version.**.** 
0df0: 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70  These features p
0e00: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
0e10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
0e20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0e30: 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49  ON].** and [SQLI
0e40: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0e50: 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74  R] #defines in t
0e60: 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61  he header, but a
0e70: 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  re associated.**
0e80: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
0e90: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
0ea0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43   header file.  C
0eb0: 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d  autious programm
0ec0: 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63  ers might.** inc
0ed0: 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20  lude a check in 
0ee0: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
0ef0: 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  n to verify that
0f00: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
0f10: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
0f20: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
0f30: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c  he value.** [SQL
0f40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f50: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ER]..**.** The s
0f60: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0f70: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
0f80: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e  urns the same in
0f90: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a  formation as is.
0fa0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ** in the sqlite
0fb0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
0fc0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
0fd0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  e function is pr
0fe0: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73  ovided.** for us
0ff0: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1000: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1010: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69  y do not have di
1020: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
1030: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e  tring.** constan
1040: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1050: 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
1060: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  NTS:.**.** {F100
1070: 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
1080: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1090: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
10a0: 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
10b0: 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65      an integer e
10c0: 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  qual to [SQLITE_
10d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
10e0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 32 7d 20  .**.** {F10022} 
10f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  The [sqlite3_ver
1100: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
1110: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a  stant contains.*
1120: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
1130: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
1140: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
1150: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32  ng..**.** {F1002
1160: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1170: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75  libversion()] fu
1180: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a  nction returns.*
1190: 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69  *          a poi
11a0: 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
11b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74  ite3_version] st
11c0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a  ring constant..*
11d0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
11e0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
11f0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
1200: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1210: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1220: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1240: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1250: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1260: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1270: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1280: 66 65 20 7b 46 31 30 31 30 30 7d 0a 2a 2a 0a 2a  fe {F10100}.**.*
1290: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
12a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
12b0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
12c0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 53  .  When.** the S
12d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12e0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
12f0: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d  macro is true, m
1300: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1310: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1320: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1330: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f   When that macro
1340: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68   is false,.** th
1350: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1360: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1370: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1380: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1390: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
13a0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
13b0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
13c0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
13d0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
13e0: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
13f0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1400: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** 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 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  by a pointer to 
1720: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a  an instance of.*
1730: 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72  * the opaque str
1740: 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71  ucture named "sq
1750: 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75  lite3".  It is u
1760: 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f  seful to think o
1770: 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20  f an sqlite3.** 
1780: 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62  pointer as an ob
1790: 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69  ject.  The [sqli
17a0: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
17b0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
17c0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
17d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
17e0: 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63  rfaces are its c
17f0: 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64  onstructors, and
1800: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1810: 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73  )].** is its des
1820: 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20  tructor.  There 
1830: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69  are many other i
1840: 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20  nterfaces (such 
1850: 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  as.** [sqlite3_p
1860: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
1870: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1880: 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a  nction()], and.*
1890: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
18a0: 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61  timeout()] to na
18b0: 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68  me but three) th
18c0: 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f  at are methods o
18d0: 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20  n an.** sqlite3 
18e0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
18f0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1900: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a  3 sqlite3;../*.*
1910: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42  * CAPI3REF: 64-B
1920: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73  it Integer Types
1930: 20 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59   {F10200}.** KEY
1940: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e  WORDS: sqlite_in
1950: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
1960: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  4.**.** Because 
1970: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73  there is no cros
1980: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74  s-platform way t
1990: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74  o specify 64-bit
19a0: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a   integer types.*
19b0: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65  * SQLite include
19c0: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  s typedefs for 6
19d0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
19e0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
19f0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
1a00: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
1a10: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
1a20: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
1a30: 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e   type definition
1a40: 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  s..** The sqlite
1a50: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1a60: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
1a70: 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  re supported for
1a80: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
1a90: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
1aa0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1ab0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  TS:.**.** {F1020
1ac0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69  1} The [sqlite_i
1ad0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
1ae0: 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20  e3_int64] types 
1af0: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1b00: 20 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67      a 64-bit sig
1b10: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1b20: 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20  ** {F10202} The 
1b30: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1b40: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1b50: 74 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69  t64] types speci
1b60: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1b70: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1b80: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
1b90: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1ba0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
1bb0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1bc0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
1bd0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1be0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
1bf0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
1c00: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
1c10: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
1c20: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
1c30: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
1c40: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
1c50: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1c60: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
1c70: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1c80: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
1c90: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1ca0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
1cb0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
1cc0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1cd0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
1ce0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
1cf0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
1d00: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
1d10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
1d20: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
1d30: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
1d40: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
1d50: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
1d60: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
1d70: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
1d80: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
1d90: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
1da0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
1db0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
1dc0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
1dd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
1de0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
1df0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
1e00: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
1e10: 63 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a  ction {F12010}.*
1e20: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1e30: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
1e40: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
1e50: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
1e60: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1e70: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
1e80: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
1e90: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
1ea0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
1eb0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
1ec0: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
1ed0: 73 65 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  se] all [sqlite3
1ee0: 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42 73 5d 20 61  _blob | BLOBs] a
1ef0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1f00: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
1f10: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20  object prior to 
1f20: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
1f30: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a  ose the object..
1f40: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1f50: 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74  next_stmt()] int
1f60: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1f70: 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ed to locate all
1f80: 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1f90: 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69  atements] associ
1fa0: 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1fb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fc0: 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a  ] if desired..**
1fd0: 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69   Typical code mi
1fe0: 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68  ght look like th
1ff0: 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
2000: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73  quote><pre>.** s
2010: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2020: 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70  mt;.** while( (p
2030: 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e  Stmt = sqlite3_n
2040: 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29  ext_stmt(db, 0))
2050: 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b  !=0 ){.** &nbsp;
2060: 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c     sqlite3_final
2070: 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d  ize(pStmt);.** }
2080: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2090: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66  kquote>.**.** If
20a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
20b0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  )] is invoked wh
20c0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
20d0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
20e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
20f0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2100: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
2110: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2120: 0a 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65  .** {F12011} The
2130: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2140: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
2150: 74 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65  troys an [sqlite
2160: 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20  3] object.**    
2170: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20        allocated 
2180: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
2190: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
21a0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
21b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
21c0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
21d0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  _open_v2()]..**.
21e0: 2a 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20  ** {F12012} The 
21f0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2200: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61  ] function relea
2210: 73 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75  ses all memory u
2220: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  sed by the.**   
2230: 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f         connectio
2240: 6e 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c  n and closes all
2250: 20 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a   open files..**.
2260: 2a 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74  ** {F12013} If t
2270: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2280: 65 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 20  ection contains 
2290: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22a0: 65 6e 74 73 5d 20 74 68 61 74 0a 2a 2a 20 20 20  ents] that.**   
22b0: 20 20 20 20 20 20 20 68 61 76 65 20 6e 6f 74 20         have not 
22c0: 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
22d0: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
22e0: 65 64 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ed],.**         
22f0: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63   then [sqlite3_c
2300: 6c 6f 73 65 28 29 5d 20 72 65 74 75 72 6e 73 20  lose()] returns 
2310: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
2320: 64 20 6c 65 61 76 65 73 0a 2a 2a 20 20 20 20 20  d leaves.**     
2330: 20 20 20 20 20 74 68 65 20 63 6f 6e 6e 65 63 74       the connect
2340: 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20  ion open..**.** 
2350: 7b 46 31 32 30 31 34 7d 20 50 61 73 73 69 6e 67  {F12014} Passing
2360: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2370: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2380: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2390: 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  -op..**.** {F120
23a0: 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  19} When [sqlite
23b0: 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e  3_close()] is in
23c0: 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  voked on a [data
23d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
23f0: 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20  t has a pending 
2400: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2410: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61   transaction sha
2420: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ll be.**        
2430: 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a    rolled back..*
2440: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
2450: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d  :.**.** {U12015}
2460: 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   The parameter t
2470: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2480: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b  ()] must be an [
2490: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a  sqlite3] object.
24a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
24b0: 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  ter previously o
24c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
24d0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
24e0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24f0: 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
2500: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  NULL..**.** {U12
2510: 30 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74  016} The paramet
2520: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2530: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74  lose()] must not
2540: 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69   have been previ
2550: 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
2560: 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74    closed..*/.int
2570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
2580: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
2590: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
25a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
25b0: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
25c0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
25d0: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
25e0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
25f0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
2600: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
2610: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
2620: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
2630: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
2640: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
2650: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
2660: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
2670: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
2680: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b  tion Interface {
2690: 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12100}.**.** Th
26a0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
26b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
26c0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
26d0: 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72  f running one or
26e0: 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61   more.** SQL sta
26f0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
2700: 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20  having to write 
2710: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
2720: 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f    The UTF-8 enco
2730: 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ded.** SQL state
2740: 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64  ments are passed
2750: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e   in as the secon
2760: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2770: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a  qlite3_exec()..*
2780: 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73  * The statements
2790: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f   are evaluated o
27a0: 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20  ne by one until 
27b0: 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20  either an error 
27c0: 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75  or.** an interru
27d0: 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65  pt is encountere
27e0: 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79  d, or until they
27f0: 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20   are all done.  
2800: 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
2810: 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f  r.** is an optio
2820: 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61  nal callback tha
2830: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  t is invoked onc
2840: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2850: 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72  f any query.** r
2860: 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20  esults produced 
2870: 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  by the SQL state
2880: 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20  ments.  The 5th 
2890: 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20  parameter tells 
28a0: 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74  where.** to writ
28b0: 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  e any error mess
28c0: 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ages..**.** The 
28d0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61  error message pa
28e0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
28f0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
2900: 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69  ter is held.** i
2910: 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
2920: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2930: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61  malloc()].  To a
2940: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
2950: 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69  ak,.** the calli
2960: 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  ng application s
2970: 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69  hould call [sqli
2980: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61  te3_free()] on a
2990: 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  ny error.** mess
29a0: 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72  age returned thr
29b0: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
29c0: 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68  ameter when it h
29d0: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
29e0: 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  g.** the error m
29f0: 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  essage..**.** If
2a00: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a10: 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  nt in the 2nd pa
2a20: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
2a30: 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
2a40: 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e  ng.** or a strin
2a50: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c  g containing onl
2a60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
2a70: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
2a80: 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  no SQL.** statem
2a90: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
2aa0: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
2ab0: 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  ase is not chang
2ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2ad0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2ae0: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
2af0: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f  ented in terms o
2b00: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
2b10: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2b20: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2b30: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2b40: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
2b50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72  sqlite3_exec() r
2b60: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68  outine does noth
2b70: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62  ing to the datab
2b80: 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ase that cannot 
2b90: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73  be done.** by [s
2ba0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bb0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2bc0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2bd0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2be0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2bf0: 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 31  TS:.** .** {F121
2c00: 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  01} A successful
2c10: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
2c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
2c30: 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20  ,C,A,E)].**     
2c40: 20 20 20 20 20 73 68 61 6c 6c 20 65 76 61 6c 75       shall evalu
2c50: 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55  ate all of the U
2c60: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 20 73 65  TF-8 encoded, se
2c70: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
2c80: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  d.**          SQ
2c90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
2ca0: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2cb0: 74 65 64 20 73 74 72 69 6e 67 20 53 20 77 69 74  ted string S wit
2cc0: 68 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hin the.**      
2cd0: 20 20 20 20 63 6f 6e 74 65 78 74 20 6f 66 20 74      context of t
2ce0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2cf0: 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
2d00: 2a 20 7b 46 31 32 31 30 32 7d 20 49 66 20 74 68  * {F12102} If th
2d10: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e S parameter to
2d20: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
2d30: 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55  ,S,C,A,E)] is NU
2d40: 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  LL then.**      
2d50: 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20      the actions 
2d60: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
2d70: 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61   shall be the sa
2d80: 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20  me as if the.** 
2d90: 20 20 20 20 20 20 20 20 20 53 20 70 61 72 61 6d           S param
2da0: 65 74 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70  eter were an emp
2db0: 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
2dc0: 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20 72 65   {F12104} The re
2dd0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
2de0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73  qlite3_exec()] s
2df0: 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  hall be [SQLITE_
2e00: 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20  OK] if all.**   
2e10: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
2e20: 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73  ments run succes
2e30: 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f  sfully and to co
2e40: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
2e50: 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65 74  {F12105} The ret
2e60: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  urn value of [sq
2e70: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
2e80: 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70  all be an approp
2e90: 72 69 61 74 65 20 0a 2a 2a 20 20 20 20 20 20 20  riate .**       
2ea0: 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72     non-zero [err
2eb0: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 20  or code] if any 
2ec0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61  SQL statement fa
2ed0: 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ils..**.** {F121
2ee0: 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f  07} If one or mo
2ef0: 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  re of the SQL st
2f00: 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20  atements handed 
2f10: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
2f20: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
2f30: 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61  return results a
2f40: 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  nd the 3rd param
2f50: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
2f60: 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
2f70: 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20     the callback 
2f80: 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69  function specifi
2f90: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
2fa0: 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65  rameter shall be
2fb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76  .**          inv
2fc0: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  oked once for ea
2fd0: 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  ch row of result
2fe0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 30 7d  ..**.** {F12110}
2ff0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
3000: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
3010: 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 5b  ero value then [
3020: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3030: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
3040: 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c 20  l abort the SQL 
3050: 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73 20  statement it is 
3060: 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75 61  currently evalua
3070: 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ting,.**        
3080: 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73 65    skip all subse
3090: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
30a0: 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72 6e  ents, and return
30b0: 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
30c0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 33 7d 20  .**.** {F12113} 
30d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
30e0: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
30f0: 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20  ll pass its 4th 
3100: 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67  parameter throug
3110: 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  h.**          as
3120: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3130: 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  er of the callba
3140: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  ck..**.** {F1211
3150: 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
3160: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3170: 73 65 74 73 20 74 68 65 20 32 6e 64 20 70 61 72  sets the 2nd par
3180: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3190: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
31a0: 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d  ck to be the num
31b0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31c0: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
31d0: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  w of.**         
31e0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
31f0: 46 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c  F12119} The [sql
3200: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
3210: 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 33 72  tine sets the 3r
3220: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
3230: 74 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts .**          
3240: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3250: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3260: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3270: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3280: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3290: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
32a0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
32b0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
32c0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
32d0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
32e0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
32f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 32 7d  ..**.** {F12122}
3300: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3310: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65  ec()] routine se
3320: 74 73 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  ts the 4th param
3330: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
3340: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
3350: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20   to be an array 
3360: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3370: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74  trings holding t
3380: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
3390: 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63  ames of result c
33a0: 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e  olumns as obtain
33b0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
33c0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
33d0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35 7d 20  .**.** {F12125} 
33e0: 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
33f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3400: 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c  _exec()] is NULL
3410: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3420: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28    [sqlite3_exec(
3430: 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 73  )] never invokes
3440: 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6c   a callback.  Al
3450: 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 20  l query.**      
3460: 20 20 20 20 72 65 73 75 6c 74 73 20 61 72 65 20      results are 
3470: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64  silently discard
3480: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  ed..**.** {F1213
3490: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
34a0: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
34b0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
34c0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
34d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
34e0: 64 65 64 20 69 6e 20 74 68 65 20 53 20 70 61 72  ded in the S par
34f0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
3500: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3510: 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20  E)] and if.**   
3520: 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61 72         the E par
3530: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ameter is not NU
3540: 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  LL, then [sqlite
3550: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
3560: 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  store.**        
3570: 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f    in *E an appro
3580: 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
3590: 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74  sage written int
35a0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
35b0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  d.**          fr
35c0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
35d0: 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  oc()]..**.** {F1
35e0: 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  2134} The [sqlit
35f0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3600: 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  E)] routine shal
3610: 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  l set the value 
3620: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  of.**          *
3630: 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69  E to NULL if E i
3640: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74  s not NULL and t
3650: 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f  here are no erro
3660: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  rs..**.** {F1213
3670: 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
3680: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3690: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
36a0: 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f  set the error co
36b0: 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  de.**          a
36c0: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
36d0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
36e0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a  e3_errcode()],.*
36f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3700: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
3710: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
3720: 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  sg16()]..**.** {
3730: 46 31 32 31 33 38 7d 20 49 66 20 74 68 65 20 53  F12138} If the S
3740: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3750: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3760: 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20  C,A,E)] is NULL 
3770: 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  or an.**        
3780: 20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f    empty string o
3790: 72 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69  r contains nothi
37a0: 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68  ng other than wh
37b0: 69 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e  itespace, commen
37c0: 74 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts,.**          
37d0: 61 6e 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e  and/or semicolon
37e0: 73 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20  s, then results 
37f0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  of [sqlite3_errc
3800: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
3810: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
3820: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
3830: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3840: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3850: 6c 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69  ll reset to indi
3860: 63 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a  cate no errors..
3870: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
3880: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31  S:.**.** {U12141
3890: 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
38a0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
38b0: 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62  3_exec()] must b
38c0: 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f  e an valid and o
38d0: 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pen.**          
38e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38f0: 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  tion]..**.** {U1
3900: 32 31 34 32 7d 20 54 68 65 20 64 61 74 61 62 61  2142} The databa
3910: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
3920: 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64  st not be closed
3930: 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20   while.**       
3940: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63     [sqlite3_exec
3950: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ()] is running..
3960: 2a 2a 20 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20  ** .** {U12143} 
3970: 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
3980: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
3990: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
39a0: 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20   to free.**     
39b0: 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20       the memory 
39c0: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
39d0: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
39e0: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
39f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73  **          mess
3a00: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
3a10: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   needed..**.** {
3a20: 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20  U12145} The SQL 
3a30: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
3a40: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3a50: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3a60: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
3a70: 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20      must remain 
3a80: 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20  unchanged while 
3a90: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3aa0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
3ab0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3ac0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3af0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3b00: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3b10: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3b20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b30: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3b40: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3b50: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3b60: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3b70: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3b80: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3b90: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3bc0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3bd0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3be0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c00: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3c10: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3c20: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3c30: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3c40: 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31 30  lt Codes {F10210
3c50: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  }.** KEYWORDS: S
3c60: 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20  QLITE_OK {error 
3c70: 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64  code} {error cod
3c80: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
3c90: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
3ca0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
3cb0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
3cc0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
3cd0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
3ce0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
3cf0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3d00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3d10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3d20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3d30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3d40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3d50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3d60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3d70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3d80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3d90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3da0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3db0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3dc0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3dd0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3df0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3e00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3e10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3e20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3e40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3e50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3e70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3e80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3e90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3ea0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3eb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3ec0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3ed0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3ee0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
3f00: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
3f10: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
3f20: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
3f30: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3f40: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
3f50: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
3f60: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
3f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
3f80: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
3f90: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
3fa0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
3fb0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
3fc0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
3fd0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
3fe0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
3ff0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4000: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4020: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4030: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4040: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4050: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4060: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4070: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4080: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4090: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
40a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
40b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
40c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
40d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
40e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
40f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4100: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4110: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4120: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4130: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4140: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4150: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4160: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4170: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4190: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
41a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
41b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
41c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
41d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
41e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
41f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4200: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4210: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4220: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4230: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4240: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4250: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4260: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4270: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4280: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
42a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
42b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
42c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
42d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
42e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
42f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4300: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4320: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4330: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4340: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4360: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4370: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4380: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4390: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
43b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
43c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
43d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
43e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
43f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4400: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4410: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4430: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4440: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4450: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4460: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4480: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4490: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
44a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
44b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
44d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
44e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
44f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4500: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4510: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4520: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4530: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4540: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4550: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4560: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4570: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4580: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4590: 65 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b  es {F10220}.** K
45a0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
45b0: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
45c0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
45d0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
45e0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
45f0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
4600: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
4610: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
4620: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
4630: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
4640: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
4650: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
4660: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4670: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4680: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4690: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
46a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
46b0: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
46c0: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
46d0: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
46e0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
46f0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4700: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4710: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4720: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4730: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4740: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4750: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4760: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4770: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4780: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4790: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
47a0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
47b0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
47c0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
47d0: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e  rrors. The exten
47e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
47f0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
4800: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61  disabled.** on a
4810: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f   per database co
4820: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75  nnection basis u
4830: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4840: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4850: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
4860: 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  I..** .** Some o
4870: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
4880: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4890: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
48a0: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
48b0: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
48c0: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
48d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
48e0: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
48f0: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
4900: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
4910: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4920: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
4930: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
4940: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
4950: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
4960: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4970: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
4980: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
4990: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
49a0: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
49b0: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
49c0: 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e   zero..** .** IN
49d0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
49e0: 7b 46 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d  {F10223} The sym
49f0: 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61  bolic name for a
4a00: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
4a10: 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63 6f  t code always co
4a20: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
4a30: 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72 69     a related pri
4a40: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
4a50: 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a   as a prefix..**
4a60: 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 72 69  .** {F10224} Pri
4a70: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
4a80: 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 61   names contain a
4a90: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72   single "_" char
4aa0: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  acter..**.** {F1
4ab0: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72  0225} Extended r
4ac0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
4ad0: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20   contain two or 
4ae0: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74  more "_" charact
4af0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ers..**.** {F102
4b00: 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 20  26} The numeric 
4b10: 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65  value of an exte
4b20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b30: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
4b40: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69            numeri
4b50: 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63  c value of its c
4b60: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69  orresponding pri
4b70: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
4b80: 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
4b90: 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66  its least signif
4ba0: 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f  icant 8 bits..*/
4bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bc0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
4bd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4be0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
4bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4c00: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
4c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4c20: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
4c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4c40: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
4c50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c60: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c80: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
4c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ca0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
4cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4cc0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
4cd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ce0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
4cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4d00: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
4d10: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4d20: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
4d30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4d40: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
4d50: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d60: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
4d70: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
4d80: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
4d90: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4da0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
4db0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
4dc0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
4dd0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4de0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
4df0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
4e00: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
4e10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4e20: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
4e30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
4e40: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
4e50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4e60: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
4e70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
4e80: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
4e90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4ea0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
4eb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
4ec0: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
4ed0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4ee0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
4ef0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
4f00: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
4f10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f20: 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  14<<8))../*.** C
4f30: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
4f40: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
4f50: 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30 7d  rations {F10230}
4f60: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
4f70: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
4f80: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
4f90: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
4fa0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
4fb0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
4fc0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
4fd0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
4fe0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70  meter to the xOp
4ff0: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
5000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
5010: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
5020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5030: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5040: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5060: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5070: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5090: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
50a0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
50b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
50c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
50d0: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
50e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
50f0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5100: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
5110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5120: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5130: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
5140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5150: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5160: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5180: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5190: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
51a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
51b0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
51c0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
51d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
51e0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
51f0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
5200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5210: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5220: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5240: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5250: 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a    0x00004000../*
5260: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
5270: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
5280: 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a 2a  tics {F10240}.**
5290: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
52a0: 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68  apabilities meth
52b0: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
52c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
52d0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
52e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
52f0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
5300: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
5310: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5320: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5330: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5340: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5350: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5360: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5380: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5390: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
53a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
53b0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
53c0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
53d0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
53e0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
53f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5400: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5410: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5420: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5430: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5440: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5450: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
5460: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
5470: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
5480: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
5490: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
54a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
54b0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
54c0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
54d0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
54e0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
54f0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
5500: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5510: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5520: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5530: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5540: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
5550: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
5560: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5570: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
5580: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5590: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
55a0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
55b0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
55c0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
55d0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
55e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
55f0: 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  C          0x000
5600: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5610: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5620: 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30  C512       0x000
5630: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5640: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5650: 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C1K        0x000
5660: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5670: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5680: 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C2K        0x000
5690: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
56a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
56b0: 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C4K        0x000
56c0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
56d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
56e0: 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C8K        0x000
56f0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
5700: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5710: 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30  C16K       0x000
5720: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
5730: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5740: 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30  C32K       0x000
5750: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5770: 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30  C64K       0x000
5780: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5790: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
57a0: 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30  APPEND     0x000
57b0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
57c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
57d0: 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30  NTIAL      0x000
57e0: 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00400../*.** CAP
57f0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
5800: 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30 32  ing Levels {F102
5810: 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  50}.**.** SQLite
5820: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
5830: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
5840: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
5850: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
5860: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
5870: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
5880: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
5890: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
58a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
58b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
58d0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
58f0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
5900: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
5910: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5920: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
5930: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
5940: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
5950: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5960: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
5970: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5980: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
5990: 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31 30   Type Flags {F10
59a0: 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  260}.**.** When 
59b0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
59c0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
59d0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
59e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
59f0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
5a00: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
5a10: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
5a20: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
5a30: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
5a40: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
5a50: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5a60: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
5a70: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
5a80: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
5a90: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
5aa0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
5ab0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
5ac0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
5ad0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
5ae0: 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53  e flushed. The S
5af0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
5b00: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a  L flag means .**
5b10: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
5b20: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
5b30: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
5b40: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
5b50: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  s .** to use Mac
5b60: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
5b70: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
5b80: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
5ba0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
5bb0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5bc0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
5bd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5bf0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
5c00: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
5c10: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
5c20: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
5c30: 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31 31 30  e Handle {F11110
5c40: 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  }.**.** An [sqli
5c50: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
5c60: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
5c70: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
5c80: 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  OS.** interface 
5c90: 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75  layer.  Individu
5ca0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  al OS interface 
5cb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
5cc0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
5cd0: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
5ce0: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
5cf0: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
5d00: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
5d10: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
5d20: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
5d30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
5d40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5d50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5d60: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
5d70: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
5d80: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
5d90: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
5da0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
5db0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5dc0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
5dd0: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
5de0: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
5df0: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
5e00: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
5e10: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
5e20: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
5e30: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
5e40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
5e50: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
5e60: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
5e70: 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a 2a 2a  ject {F11120}.**
5e80: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
5e90: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
5ea0: 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e  lite3_vfs] xOpen
5eb0: 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73   method contains
5ec0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
5ed0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
5ee0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54 68  this object.  Th
5ef0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
5f00: 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73  s the.** methods
5f10: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
5f20: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
5f30: 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  ons against the 
5f40: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  open file..**.**
5f50: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
5f60: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
5f70: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
5f80: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
5f90: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
5fa0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
5fb0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
5fc0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
5fd0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
5fe0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
5ff0: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
6000: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
6010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6020: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
6030: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
6040: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
6050: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
6060: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
6070: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
6080: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 20  o be synced..** 
6090: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
60a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
60b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
60c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
60d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
60e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
60f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6100: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
6110: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6120: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6140: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6150: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6160: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6170: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6180: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
6190: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
61a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
61b0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78  lock.  .** The x
61c0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
61d0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
61e0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
61f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6200: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
6210: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
6220: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
6230: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
6240: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
6250: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
6260: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
6270: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
6280: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
6290: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
62a0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
62b0: 65 72 77 69 73 65 2e 0a 2a 2a 20 0a 2a 2a 20 54  erwise..** .** T
62c0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
62d0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
62e0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
62f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
6300: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
6310: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
6320: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
6330: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
6340: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6350: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
6360: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
6370: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
6380: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
6390: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
63a0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
63b0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
63c0: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
63d0: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
63e0: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
63f0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
6400: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
6410: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
6420: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
6430: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
6440: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6450: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6460: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6470: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6480: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6490: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
64a0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
64b0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
64c0: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
64d0: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
64e0: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
64f0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
6500: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
6510: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
6520: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
6530: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
6540: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6550: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6560: 77 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53  wn use. .** A [S
6570: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6580: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6590: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
65a0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
65b0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
65c0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
65d0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
65e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
65f0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6600: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6610: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6620: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6630: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6640: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6650: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6660: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6670: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6680: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6690: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
66a0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
66b0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
66c0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
66d0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
66e0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
66f0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6700: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6710: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6720: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6730: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6740: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6750: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6760: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6770: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6780: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6790: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
67b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
67c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
67d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
67e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
67f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6800: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
6810: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6820: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6830: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6840: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6850: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6860: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6870: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6890: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
68a0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
68b0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
68c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
68d0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
68e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
68f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6900: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6910: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6920: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6930: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6950: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6960: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6970: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6980: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6990: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
69a0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
69b0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
69c0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
69d0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
69e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
69f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6a00: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6a10: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6a20: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6a30: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6a40: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6a50: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6a60: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6a70: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6a80: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6a90: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6aa0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6ab0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6ac0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6ad0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6ae0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6af0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6b00: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6b10: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
6b20: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6b30: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6b40: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6b50: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6b60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6b70: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
6b80: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
6b90: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
6ba0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
6bb0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
6bc0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
6bd0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
6be0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
6bf0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
6c00: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
6c10: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6c20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6c30: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6c40: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6c50: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6c60: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6c70: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6c80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
6c90: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
6ca0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
6cb0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6cc0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
6cd0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
6ce0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6cf0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
6d00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6d10: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6d20: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6d30: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6d40: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
6d50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6d60: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6d70: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6d80: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6d90: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6da0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6db0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6dc0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6dd0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6de0: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6df0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6e00: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6e10: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6e20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6e30: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6e40: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6e50: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
6e60: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
6e70: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
6e80: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6ea0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6eb0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ec0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
6ed0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
6ee0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
6ef0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
6f00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
6f10: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
6f20: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
6f30: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
6f40: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
6f50: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
6f60: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
6f70: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
6f80: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
6f90: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
6fa0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
6fb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6fc0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
6fd0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
6fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ff0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7000: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7010: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7020: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7030: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7040: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7050: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7060: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7070: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7080: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7090: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
70a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
70b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
70c0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
70d0: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a          1../*.**
70e0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
70f0: 20 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d   Handle {F17110}
7100: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
7110: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
7120: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
7130: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
7140: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
7150: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
7160: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
7170: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
7180: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
7190: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
71a0: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
71b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
71c0: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
71d0: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
71e0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
71f0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
7200: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
7210: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
7220: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
7230: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
7240: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7250: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
7260: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
7270: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7280: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46  erface Object {F
7290: 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  11140}.**.** An 
72a0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
72b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
72c0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
72d0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
72e0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
72f0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7300: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
7310: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
7320: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
7330: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
7340: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
7350: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
7360: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
7370: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
7380: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
7390: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
73a0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
73b0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
73c0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
73d0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
73e0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
73f0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
7400: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
7410: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
7420: 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
7430: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
7440: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
7450: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
7460: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
7470: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
7480: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
7490: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
74a0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
74b0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
74c0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
74d0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
74e0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
74f0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
7500: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
7510: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
7520: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
7530: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
7540: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
7550: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
7560: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
7570: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
7580: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
7590: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
75a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
75b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
75c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
75d0: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
75e0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
75f0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
7600: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
7610: 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72  vfs .** structur
7620: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7630: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7640: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7650: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
7660: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
7670: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
7680: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
7690: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
76a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
76b0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
76c0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
76d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
76e0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
76f0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
7700: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7710: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7720: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7730: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7740: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7750: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
7760: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
7770: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
7780: 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74  * {F11141} SQLit
7790: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
77a0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
77b0: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
77c0: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
77d0: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
77e0: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
77f0: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
7800: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
7810: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
7820: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
7830: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
7840: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
7850: 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65  d.  {END} So the
7860: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7870: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
7880: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
7890: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
78a0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
78b0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
78c0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
78d0: 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20  ** {F11142} The 
78e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
78f0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
7900: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
7910: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
7920: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
7930: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
7940: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
7950: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
7960: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
7970: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
7980: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
7990: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
79a0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
79b0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
79c0: 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d  N_CREATE]. {END}
79d0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
79e0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
79f0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
7a00: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
7a10: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
7a20: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7a30: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
7a40: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
7a50: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
7a60: 7b 46 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20  {F11143} SQLite 
7a70: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
7a80: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
7a90: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
7aa0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
7ab0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
7ac0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
7ad0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
7ae0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
7af0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
7b00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7b10: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
7b20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7b30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
7b40: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
7b50: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
7b60: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
7b70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
7b80: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
7b90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7ba0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
7bb0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7bc0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
7bd0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  AL].** </ul> {EN
7be0: 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  D}.**.** The fil
7bf0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
7c00: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
7c10: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
7c20: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
7c30: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
7c40: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
7c50: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
7c60: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
7c70: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
7c80: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
7c90: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
7ca0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
7cb0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
7cc0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
7cd0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
7ce0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
7cf0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
7d00: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
7d10: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
7d20: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
7d30: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
7d40: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
7d50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
7d60: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
7d70: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
7d80: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7d90: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7da0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7db0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7dc0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
7dd0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
7de0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
7df0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
7e00: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
7e10: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
7e20: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
7e30: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
7e40: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
7e50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
7e60: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
7e70: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7e80: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7e90: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
7ea0: 20 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53   {F11145} The [S
7eb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7ec0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
7ed0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7ee0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
7ef0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
7f00: 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20  osed.  {F11146} 
7f10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7f20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
7f30: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
7f40: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
7f50: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
7f60: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
7f70: 2e 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68  ..** {F11147} Th
7f80: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
7f90: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
7fa0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7fb0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
7fc0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
7fd0: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
7fe0: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
7ff0: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
8000: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
8010: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b 45  atabase file. {E
8020: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  ND}.**.** {F1114
8030: 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  8} At least szOs
8040: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
8050: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
8060: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
8070: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
8080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
8090: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
80a0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
80b0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
80c0: 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65   {END}  The xOpe
80d0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
80e0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
80f0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
8100: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
8110: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a  ust fill it in..
8120: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54  **.** {F11149} T
8130: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8140: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
8150: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
8160: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8170: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8180: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8190: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
81a0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
81b0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
81c0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
81d0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
81e0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
81f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
8200: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
8210: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
8220: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 7b  ast readable.  {
8230: 45 4e 44 7d 20 54 68 65 20 66 69 6c 65 20 63 61  END} The file ca
8240: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
8250: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  ory..**.** {F111
8260: 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  50} SQLite will 
8270: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
8280: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
8290: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
82a0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
82b0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
82c0: 6d 65 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65  me. {F11151} The
82d0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
82e0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
82f0: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
8300: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
8310: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
8320: 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65  ds. {END} If the
8330: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
8340: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
8350: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
8360: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
8370: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
8380: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
8390: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
83a0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
83b0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
83c0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
83d0: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
83e0: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
83f0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
8400: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
8410: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
8420: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8430: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
8440: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
8450: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
8460: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
8470: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
8480: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
8490: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
84a0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
84b0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
84c0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
84d0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
84e0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
84f0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
8500: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
8510: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
8520: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
8530: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
8540: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
8550: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
8560: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
8570: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
8580: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
8590: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
85a0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
85b0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
85c0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
85d0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
85e0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
85f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
8600: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
8610: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
8620: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
8630: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
8640: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  me..*/.typedef s
8650: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8660: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
8670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
8680: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8690: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
86a0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
86b0: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
86c0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
86d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
86e0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
86f0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
8700: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
8710: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
8720: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
8730: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
8740: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
8750: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
8760: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
8770: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
8780: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
8790: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
87a0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
87b0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
87c0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
87d0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
87e0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
87f0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
8800: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
8810: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8820: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
8830: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
8840: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
8850: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
8860: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
8870: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
8880: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8890: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
88a0: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
88b0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
88c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
88d0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
88e0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
88f0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
8900: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
8910: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8920: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
8930: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
8940: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
8950: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8960: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
8970: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
8980: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
8990: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
89a0: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
89b0: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  g);.  void *(*xD
89c0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
89d0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
89e0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
89f0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
8a00: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8a10: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
8a20: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
8a30: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
8a40: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
8a50: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
8a60: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
8a70: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
8a80: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
8a90: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
8aa0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
8ab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
8ac0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
8ad0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
8ae0: 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66  r *);.  /* New f
8af0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
8b00: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
8b10: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
8b20: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
8b30: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
8b40: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
8b50: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a  happens. */.};..
8b60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8b70: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
8b80: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
8b90: 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20   {F11190}.**.** 
8ba0: 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65 20 69  {F11191} These i
8bb0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
8bc0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
8bd0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
8be0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
8bf0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
8c00: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
8c10: 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20   object. {END}  
8c20: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
8c30: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
8c40: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
8c50: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
8c60: 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e  .** looking for.
8c70: 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74 68 20    {F11192} With 
8c80: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8c90: 58 49 53 54 53 5d 2c 20 74 68 65 20 78 41 63 63  XISTS], the xAcc
8ca0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
8cb0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
8cc0: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
8cd0: 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20  xists. {F11193} 
8ce0: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
8cf0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
8d00: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8d10: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
8d20: 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  e.** if the file
8d30: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
8d40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  e and writable. 
8d50: 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a   {F11194} With.*
8d60: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
8d70: 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73  READ the xAccess
8d80: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
8d90: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
8da0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
8db0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8dc0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8dd0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8de0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8df0: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8e00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8e10: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8e20: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
8e30: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
8e40: 65 20 4c 69 62 72 61 72 79 20 7b 46 31 30 31 33  e Library {F1013
8e50: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
8e60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8e70: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
8e80: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
8e90: 69 74 65 20 6c 69 62 72 61 72 79 20 70 72 69 6f  ite library prio
8ea0: 72 20 74 6f 20 75 73 65 2e 20 20 54 68 65 20 73  r to use.  The s
8eb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
8ec0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
8ed0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
8ee0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
8ef0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
8f00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8f10: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  ()..**.** A call
8f20: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
8f30: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
8f40: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
8f50: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
8f60: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
8f70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8f80: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
8f90: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
8fa0: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
8fb0: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
8fc0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
8fd0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8fe0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
8ff0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
9000: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9010: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e  down().  Only an
9020: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9030: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9040: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9050: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9060: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9070: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9080: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 20 20 49 6e  less no-ops.  In
9090: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
90a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   the sqlite3_ini
90b0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
90c0: 65 20 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20  e may be called 
90d0: 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 0a 2a  multiple times.*
90e0: 2a 20 77 69 74 68 6f 75 74 20 63 6f 6e 73 65 71  * without conseq
90f0: 75 65 6e 63 65 2e 20 20 53 65 63 6f 6e 64 20 61  uence.  Second a
9100: 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 65 76  nd subsequent ev
9110: 61 6c 75 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  aluations of.** 
9120: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9130: 7a 65 28 29 20 61 72 65 20 6e 6f 2d 6f 70 73 2e  ze() are no-ops.
9140: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e    The sqlite3_in
9150: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
9160: 6e 65 0a 2a 2a 20 6f 6e 6c 79 20 77 6f 72 6b 73  ne.** only works
9170: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9180: 69 74 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  it is called for
9190: 20 61 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 74   a process, or t
91a0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 74 69 6d 65  he first.** time
91b0: 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 61 66   it is called af
91c0: 74 65 72 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ter sqlite3_shut
91d0: 64 6f 77 6e 28 29 2e 20 20 49 6e 20 61 6c 6c 20  down().  In all 
91e0: 6f 74 68 65 72 20 63 61 73 65 73 2c 0a 2a 2a 20  other cases,.** 
91f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9200: 7a 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ze() returns SQL
9210: 49 54 45 5f 4f 4b 20 77 69 74 68 6f 75 74 20 64  ITE_OK without d
9220: 6f 69 6e 67 20 61 6e 79 20 72 65 61 6c 20 77 6f  oing any real wo
9230: 72 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  rk..**.** Among 
9240: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71  other things, sq
9250: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9260: 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a  () shall invoke.
9270: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9280: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9290: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  , sqlite3_shutdo
92a0: 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e  wn().** shall in
92b0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
92c0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  end()..**.** The
92d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
92e0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
92f0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20  turns SQLITE_OK 
9300: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49  on success..** I
9310: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
9320: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
9330: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
9340: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
9350: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
9360: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
9370: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
9380: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
9390: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
93a0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
93b0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
93c0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c  ] other than SQL
93d0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68  ITE_OK..**.** Th
93e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
93f0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9400: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
9410: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
9420: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
9430: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
9440: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
9450: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
9460: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
9470: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9480: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
9490: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
94a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
94b0: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
94c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
94d0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
94e0: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
94f0: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
9500: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
9510: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
9520: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
9530: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
9540: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
9550: 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51    However, if SQ
9560: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9570: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
9580: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a  _OMIT_AUTOINIT.*
9590: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
95a0: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
95b0: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
95c0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
95d0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
95e0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
95f0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
9600: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
9610: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
9620: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
9630: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9640: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9650: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
9660: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
9670: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
9680: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
9690: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
96a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
96b0: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
96c0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
96d0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
96e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
96f0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
9700: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
9710: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
9720: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
9730: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
9740: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
9750: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
9760: 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ith SQLITE_OMIT_
9770: 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62  AUTOINIT might b
9780: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
9790: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
97a0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
97b0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
97c0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
97d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
97e0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
97f0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
9800: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
9810: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
9820: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
9830: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9840: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
9850: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
9860: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
9870: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
9880: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
9890: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
98a0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
98b0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
98c0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
98d0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
98e0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
98f0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
9900: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
9910: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
9920: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
9930: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
9940: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
9950: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
9960: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9970: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ].  .**.** The a
9980: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9990: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
99a0: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
99b0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
99c0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
99d0: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
99e0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
99f0: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
9a00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9a10: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
9a20: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
9a30: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
9a40: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
9a50: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
9a60: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
9a70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9a80: 20 61 6e 64 20 0a 2a 2a 20 73 71 6c 69 74 65 33   and .** sqlite3
9a90: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
9aa0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
9ab0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
9ac0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
9ad0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
9ae0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9af0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
9b00: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
9b10: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
9b20: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
9b30: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
9b40: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
9b50: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
9b60: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
9b70: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49   (using the SQLI
9b80: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f  TE_OS_OTHER=1 co
9b90: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
9ba0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
9bb0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
9bc0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
9bd0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
9be0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9bf0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9c00: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
9c10: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
9c20: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
9c30: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
9c40: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
9c50: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
9c60: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51  * must return SQ
9c70: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
9c80: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
9c90: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
9ca0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
9cb0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
9cc0: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
9cd0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
9ce0: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
9cf0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9d00: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
9d10: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
9d20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9d30: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
9d40: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9d50: 79 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a  y {F10145}.**.**
9d60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
9d70: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
9d80: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
9d90: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
9da0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
9db0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
9dc0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
9dd0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
9de0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
9df0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
9e00: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
9e10: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
9e20: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
9e30: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
9e40: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
9e50: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
9e60: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
9e70: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
9e80: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
9e90: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
9ea0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
9eb0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
9ec0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9ed0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
9ee0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
9ef0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
9f00: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
9f10: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
9f20: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
9f30: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
9f40: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
9f50: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
9f60: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
9f70: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
9f80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
9f90: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
9fa0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
9fb0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
9fc0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
9fd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9fe0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
9ff0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
a000: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
a010: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
a020: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63  , that sqlite3_c
a030: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
a040: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
a050: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
a060: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
a070: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
a080: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
a090: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
a0a0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
a0b0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
a0c0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
a0d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
a0e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a0f0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a100: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
a110: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
a120: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
a130: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
a140: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
a150: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
a160: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
a170: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  on the [SQLITE_C
a180: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
a190: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
a1a0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
a1b0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
a1c0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
a1d0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a1e0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a1f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a200: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
a210: 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  K..** If the opt
a220: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a230: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a240: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a250: 74 69 6f 6e 20 0a 2a 2a 20 74 68 65 6e 20 74 68  tion .** then th
a260: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
a270: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
a280: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
a290: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
a2a0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
a2b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
a2c0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
a2d0: 52 6f 75 74 69 6e 65 73 20 7b 46 31 30 31 35 35  Routines {F10155
a2e0: 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
a2f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
a300: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
a310: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
a320: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
a330: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
a340: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
a350: 6e 65 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69  nes.  .**.** Thi
a360: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
a370: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
a380: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
a390: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
a3a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a3b0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
a3c0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
a3d0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
a3e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 20 77 68  lite3_config] wh
a3f0: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
a400: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
a410: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
a420: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72  _MALLOC].  By cr
a430: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
a440: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a450: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
a460: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
a470: 63 6f 6e 66 69 67 5d 20 64 75 72 69 6e 67 20 63  config] during c
a480: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
a490: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
a4a0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
a4b0: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
a4c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
a4d0: 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51  system.** for SQ
a4e0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
a4f0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
a500: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
a510: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
a520: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
a530: 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65  th a built-in me
a540: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
a550: 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63  hat is.** perfec
a560: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
a570: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
a580: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
a590: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
a5a0: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
a5b0: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
a5c0: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
a5d0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
a5e0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
a5f0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
a600: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
a610: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
a620: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
a630: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
a640: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
a650: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
a660: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
a670: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
a680: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
a690: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
a6a0: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
a6b0: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
a6c0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
a6d0: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
a6e0: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
a6f0: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
a700: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
a710: 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e  alloc, xFree, an
a720: 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  d xRealloc metho
a730: 64 73 20 73 68 6f 75 6c 64 20 77 6f 72 6b 20 6c  ds should work l
a740: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
a750: 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64  c(), free(), and
a760: 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74   realloc() funct
a770: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
a780: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a  andard library..
a790: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
a7a0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
a7b0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
a7c0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
a7d0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
a7e0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
a7f0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
a800: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
a810: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
a820: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
a830: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
a840: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
a850: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
a860: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
a870: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
a880: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
a890: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
a8a0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
a8b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
a8c0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
a8d0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
a8e0: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
a8f0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
a900: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
a910: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
a920: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
a930: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
a940: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
a950: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
a960: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
a970: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 20  o a power of 2. 
a980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
a990: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
a9a0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
a9b0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
a9c0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
a9d0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
a9e0: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
a9f0: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
aa00: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
aa10: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
aa20: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
aa30: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
aa40: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
aa50: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
aa60: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
aa70: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
aa80: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
aa90: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
aaa0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
aab0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
aac0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
aad0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
aae0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
aaf0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
ab00: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
ab10: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
ab20: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
ab30: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
ab40: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
ab50: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
ab60: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
ab70: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
ab80: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
ab90: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
aba0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
abb0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
abc0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
abd0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
abe0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
abf0: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
ac00: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
ac10: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
ac20: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
ac30: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
ac40: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
ac50: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
ac60: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
ac70: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
ac80: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
ac90: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
aca0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
acb0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
acc0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
acd0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
ace0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
acf0: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
ad00: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
ad10: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
ad20: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
ad30: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
ad40: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
ad50: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
ad60: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
ad70: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
ad80: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
ad90: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
ada0: 20 7b 46 31 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F10160}.**.** 
adb0: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
adc0: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
add0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
ade0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
adf0: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
ae00: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
ae10: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
ae20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
ae30: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
ae40: 0a 2a 2a 20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  .** .** <dl>.** 
ae50: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ae60: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
ae70: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
ae80: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
ae90: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
aea0: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64  .  This option d
aeb0: 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
aec0: 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
aed0: 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
aee0: 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
aef0: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
af00: 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
af10: 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ead.</dd>.**.** 
af20: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
af30: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
af40: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
af50: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
af60: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
af70: 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69    This option di
af80: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
af90: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
afa0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
afb0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
afc0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
afd0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
afe0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
aff0: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
b000: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
b010: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b020: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
b030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
b040: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
b050: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
b060: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
b070: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
b080: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
b090: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
b0a0: 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  onment.</dd>.**.
b0b0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b0c0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
b0d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
b0e0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
b0f0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
b100: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
b110: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
b120: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
b130: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
b140: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
b150: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b160: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
b170: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
b180: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
b190: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
b1a0: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
b1b0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b1c0: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
b1d0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 29 20  E_THREADSAFE=1) 
b1e0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
b1f0: 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
b200: 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
b210: 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
b220: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
b230: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
b240: 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
b250: 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
b260: 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
b270: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
b280: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
b290: 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
b2a0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
b2b0: 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
b2c0: 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
b2d0: 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a  same time.</dd>.
b2e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b2f0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
b300: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
b310: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
b320: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
b330: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
b340: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
b350: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
b360: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
b370: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
b380: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
b390: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
b3a0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
b3b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
b3c0: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
b3d0: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
b3e0: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
b3f0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
b400: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
b410: 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  te.</dd>.**.** <
b420: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b430: 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
b440: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
b450: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
b460: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
b470: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
b480: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
b490: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
b4a0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
b4b0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
b4c0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b4d0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
b4e0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
b4f0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
b500: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
b510: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
b520: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
b530: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
b540: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
b550: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
b560: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
b570: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
b580: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
b590: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
b5a0: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
b5b0: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
b5c0: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
b5d0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
b5e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b5f0: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
b600: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
b610: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
b620: 62 6f 6f 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74  boolean argument
b630: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
b640: 72 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68  r disables.** th
b650: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
b660: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b670: 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 20 57  n statistics.  W
b680: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
b690: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53  e.** following S
b6a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
b6b0: 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
b6c0: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
b6d0: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
b6e0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
b6f0: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
b700: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
b710: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
b720: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
b730: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
b740: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69  ].**   <li> sqli
b750: 74 65 33 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75  te3_memory_statu
b760: 73 28 29 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  s().**   </ul>.*
b770: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
b780: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b790: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
b7a0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b7b0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
b7c0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
b7d0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
b7e0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
b7f0: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
b800: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
b810: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
b820: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
b830: 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  , the.** size of
b840: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62 75   each scratch bu
b850: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
b860: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66  he number of buf
b870: 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73  fers (N).  The s
b880: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
b890: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
b8a0: 20 6f 66 20 31 36 2e 20 54 68 65 20 66 69 72 73   of 16. The firs
b8b0: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
b8c0: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
b8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
b8e0: 74 20 6c 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e  t least (sz+4)*N
b8f0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
b900: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ..** SQLite will
b910: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
b920: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75  n one scratch bu
b930: 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72  ffer at once per
b940: 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e   thread, so.** N
b950: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
b960: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  o the expected m
b970: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b980: 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73   threads.  The s
b990: 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73  z.** parameter s
b9a0: 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73  hould be 6 times
b9b0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
b9c0: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
b9d0: 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
b9e0: 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  Scratch buffers 
b9f0: 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74  are used as part
ba00: 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61   of the btree ba
ba10: 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e  lance operation.
ba20: 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65    If.** The btre
ba30: 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73  e balancer needs
ba40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   additional memo
ba50: 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
ba60: 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a  s provided by.**
ba70: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
ba80: 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63   or if no scratc
ba90: 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69  h buffer space i
baa0: 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
bab0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73  n SQLite.** goes
bac0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
bad0: 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e  loc()] to obtain
bae0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e   the memory it n
baf0: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eeds.</dd>.**.**
bb00: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
bb10: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
bb20: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
bb30: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
bb40: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
bb50: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
bb60: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
bb70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
bb80: 67 65 20 63 61 63 68 65 2e 20 20 54 68 65 72 65  ge cache.  There
bb90: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
bba0: 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20  ents: A pointer 
bbb0: 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  to the.** memory
bbc0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
bbd0: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
bbe0: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
bbf0: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
bc00: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
bc10: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
bc20: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
bc30: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
bc40: 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  8.  The first.**
bc50: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
bc60: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
bc70: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
bc80: 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74  ast (sz+4)*N byt
bc90: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
bca0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
bcb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
bcc0: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
bcd0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
bce0: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
bcf0: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
bd00: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
bd10: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
bd20: 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74  cache.  If addit
bd30: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
bd40: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
bd50: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
bd60: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
bd70: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
bd80: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
bd90: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
bda0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
bdb0: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
bdc0: 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a  e space.</dd>.**
bdd0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bde0: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
bdf0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
be00: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
be10: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
be20: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
be30: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
be40: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
be50: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
be60: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
be70: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
be80: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
be90: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
bea0: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
beb0: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
bec0: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
bed0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
bee0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
bef0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d   memory, the num
bf00: 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
bf10: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
bf20: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
bf30: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
bf40: 20 73 69 7a 65 2e 20 20 57 68 65 6e 0a 2a 2a 20   size.  When.** 
bf50: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
bf60: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  on option is use
bf70: 64 2c 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  d, SQLite never 
bf80: 63 61 6c 6c 73 20 74 68 65 20 73 79 73 74 65 6d  calls the system
bf90: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  .** malloc() imp
bfa0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 62 75 74 20  lementation but 
bfb0: 69 6e 73 74 65 61 64 20 75 73 65 73 20 74 68 65  instead uses the
bfc0: 20 73 75 70 70 6c 69 65 64 20 6d 65 6d 6f 72 79   supplied memory
bfd0: 20 62 75 66 66 65 72 0a 2a 2a 20 74 6f 20 73 61   buffer.** to sa
bfe0: 74 69 73 66 79 20 61 6c 6c 20 5b 73 71 6c 69 74  tisfy all [sqlit
bff0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 72 65 71  e3_malloc()] req
c000: 75 65 73 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  uests.</dd>.**.*
c010: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c020: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
c030: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c040: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
c050: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
c060: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
c070: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
c080: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
c090: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
c0a0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
c0b0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
c0c0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
c0d0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
c0e0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
c0f0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
c100: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
c110: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
c120: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
c130: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c140: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
c150: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
c160: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
c170: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
c180: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
c190: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
c1a0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
c1b0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
c1c0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
c1d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
c1e0: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
c1f0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
c200: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
c210: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
c220: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  tex routines..**
c230: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
c240: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
c250: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
c260: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
c270: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
c280: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
c290: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
c2a0: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
c2b0: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
c2c0: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
c2d0: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
c2e0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
c2f0: 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
c300: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
c310: 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
c320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c330: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
c340: 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
c350: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c360: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
c370: 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
c380: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
c390: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
c3a0: 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
c3b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c3c0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
c3d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c3e0: 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
c3f0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
c400: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
c410: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
c420: 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
c430: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
c440: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
c450: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c460: 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
c470: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
c480: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
c490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c4a0: 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
c4b0: 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
c4c0: 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
c4d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c4e0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
c4f0: 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
c500: 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
c510: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
c520: 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
c530: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
c540: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c550: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c560: 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
c570: 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
c580: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
c590: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c5a0: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
c5b0: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
c5c0: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30  ult Codes {F1220
c5d0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
c5e0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
c5f0: 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
c600: 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
c610: 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
c620: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
c630: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
c640: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
c650: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ure of SQLite..*
c660: 2a 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  * The extended r
c670: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
c680: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
c690: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
c6a0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
c6b0: 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f  ity consideratio
c6c0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
c6d0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
c6e0: 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64  201} Each new [d
c6f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c700: 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74  on] shall have t
c710: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
c720: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
c730: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 64  codes] feature d
c740: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
c750: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30  lt..**.** {F1220
c760: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
c770: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
c780: 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65  codes(D,F)] inte
c790: 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62  rface shall enab
c7a0: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
c7b0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
c7c0: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 20  codes] for the  
c7d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c7e0: 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
c7f0: 20 20 20 20 69 66 20 74 68 65 20 46 20 70 61 72      if the F par
c800: 61 6d 65 74 65 72 20 69 73 20 74 72 75 65 2c 20  ameter is true, 
c810: 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20  or disable them 
c820: 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a  if F is false..*
c830: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
c840: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
c850: 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
c860: 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
c870: 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
c880: 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 46 31  Insert Rowid {F1
c890: 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68  2220}.**.** Each
c8a0: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
c8b0: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
c8c0: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
c8d0: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
c8e0: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22  key called the "
c8f0: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69  rowid". The rowi
c900: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
c910: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
c920: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
c930: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
c940: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
c950: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
c960: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
c970: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
c980: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
c990: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20   columns. If.** 
c9a0: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
c9b0: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49  column of type I
c9c0: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
c9d0: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
c9e0: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
c9f0: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
ca00: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
ca10: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
ca20: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
ca30: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
ca40: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
ca50: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ERT into the dat
ca60: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
ca70: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ca80: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
ca90: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
caa0: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
cab0: 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65   INSERTs.** have
cac0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
cad0: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
cae0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
caf0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
cb00: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
cb10: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
cb20: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
cb30: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
cb40: 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
cb50: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
cb60: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
cb70: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
cb80: 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  er is running..*
cb90: 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
cba0: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
cbb0: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
cbc0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
cbd0: 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73  utine.** reverts
cbe0: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
cbf0: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
cc00: 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66  re the trigger f
cc10: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49  ired..**.** An I
cc20: 4e 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73  NSERT that fails
cc30: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
cc40: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
cc50: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
cc60: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64  ssful INSERT and
cc70: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
cc80: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
cc90: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
cca0: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
ccb0: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
ccc0: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
ccd0: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
cce0: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
ccf0: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
cd00: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
cd10: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
cd20: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
cd30: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
cd40: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
cd50: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
cd60: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
cd70: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
cd80: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
cd90: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
cda0: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
cdb0: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
cdc0: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
cdd0: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
cde0: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
cdf0: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
ce00: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
ce10: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
ce20: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
ce30: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
ce40: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
ce50: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
ce60: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
ce70: 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20  tine, an INSERT 
ce80: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
ce90: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
cea0: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
ceb0: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
cec0: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
ced0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
cee0: 2a 20 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b  * {F12221} The [
cef0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
cf00: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
cf10: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
cf20: 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20  e rowid.**      
cf30: 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
cf40: 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
cf50: 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d  l INSERT perform
cf60: 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ed on the same.*
cf70: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
cf80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cf90: 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20   and within the 
cfa0: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c  same or higher l
cfb0: 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  evel.**         
cfc0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
cfd0: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
cfe0: 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20  re have been no 
cff0: 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72  qualifying inser
d000: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  ts..**.** {F1222
d010: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
d020: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d030: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
d040: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
d050: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65        same value
d060: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
d070: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  m the same trigg
d080: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  er context.**   
d090: 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65         immediate
d0a0: 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ly before and af
d0b0: 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a  ter a ROLLBACK..
d0c0: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
d0d0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32  S:.**.** {U12232
d0e0: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
d0f0: 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
d100: 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20  a new INSERT on 
d110: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
d120: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
d130: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
d140: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
d150: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d160: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
d170: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
d180: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
d190: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
d1a0: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
d1b0: 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
d1c0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
d1d0: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
d1e0: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
d1f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
d200: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
d210: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
d220: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
d230: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
d240: 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
d250: 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
d260: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
d270: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
d280: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
d290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d2a0: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
d2b0: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
d2c0: 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F12240}.**.** 
d2d0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
d2e0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
d2f0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
d300: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
d310: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
d320: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
d330: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
d340: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
d350: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
d360: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
d370: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
d380: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
d390: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
d3a0: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
d3b0: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
d3c0: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
d3d0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
d3e0: 2a 2a 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  ** or DELETE sta
d3f0: 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
d400: 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
d410: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
d420: 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65  .** triggers are
d430: 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73   not counted. Us
d440: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
d450: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
d460: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
d470: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
d480: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
d490: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
d4a0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
d4b0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72  gers..**.** A "r
d4c0: 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
d4d0: 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
d4e0: 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
d4f0: 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
d500: 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
d510: 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
d520: 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
d530: 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
d540: 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
d550: 65 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41  effects of REPLA
d560: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
d570: 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
d580: 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
d590: 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41  cessing, DROP TA
d5a0: 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  BLE, or by any o
d5b0: 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
d5c0: 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
d5d0: 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
d5e0: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22  anges..**.** A "
d5f0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
d600: 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
d610: 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
d620: 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
d630: 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
d640: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
d650: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
d660: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
d670: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
d680: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
d690: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
d6a0: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
d6b0: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
d6c0: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
d6d0: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
d6e0: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
d6f0: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
d700: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
d710: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
d720: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
d730: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
d740: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
d750: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
d760: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
d770: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
d780: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
d790: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
d7a0: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
d7b0: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
d7c0: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
d7d0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
d7e0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
d7f0: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
d800: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
d810: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
d820: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
d830: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
d840: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
d850: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
d860: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
d870: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
d880: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
d890: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
d8a0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
d8b0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
d8c0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
d8d0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
d8e0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
d8f0: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
d900: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
d910: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
d920: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
d930: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
d940: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
d950: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
d960: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
d970: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
d980: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
d990: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
d9a0: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
d9b0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
d9c0: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
d9d0: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
d9e0: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
d9f0: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
da00: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
da10: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
da20: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
da30: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
da40: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
da50: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
da60: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
da70: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
da80: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
da90: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
daa0: 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45   without a WHERE
dab0: 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72   clause.** by dr
dac0: 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
dad0: 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
dae0: 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20    (This is much 
daf0: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
db00: 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
db10: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
db20: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
db30: 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  om the table.)  
db40: 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  Because of this.
db50: 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  ** optimization,
db60: 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69   the deletions i
db70: 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  n "DELETE FROM t
db80: 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f  able" are not ro
db90: 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a  w changes and.**
dba0: 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75   will not be cou
dbb0: 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  nted by the sqli
dbc0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72  te3_changes() or
dbd0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
dbe0: 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75  changes()].** fu
dbf0: 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c  nctions, regardl
dc00: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
dc10: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
dc20: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
dc30: 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62  ly.** in the tab
dc40: 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61  le.  To get an a
dc50: 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
dc60: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
dc70: 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
dc80: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
dc90: 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
dca0: 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49  instead..**.** I
dcb0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
dcc0: 20 7b 46 31 32 32 34 31 7d 20 54 68 65 20 5b 73   {F12241} The [s
dcd0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
dce0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
dcf0: 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   return the numb
dd00: 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
dd10: 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61    row changes ca
dd20: 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  used by the most
dd30: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
dd40: 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20  UPDATE,.**      
dd50: 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74      or DELETE st
dd60: 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73  atement on the s
dd70: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
dd80: 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  nection and.**  
dd90: 20 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74          within t
dda0: 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65  he same or highe
ddb0: 72 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  r trigger contex
ddc0: 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68  t, or zero if th
ddd0: 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20  ere have.**     
dde0: 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e       not been an
ddf0: 79 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77  y qualifying row
de00: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
de10: 7b 46 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65  {F12243} Stateme
de20: 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  nts of the form 
de30: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
de40: 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a  lename" with no.
de50: 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52  **          WHER
de60: 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63  E clause shall c
de70: 61 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  ause subsequent 
de80: 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
de90: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68       [sqlite3_ch
dea0: 61 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75  anges()] to retu
deb0: 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c  rn zero, regardl
dec0: 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ess of the.**   
ded0: 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
dee0: 20 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79   rows originally
def0: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a   in the table..*
df00: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
df10: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d  :.**.** {U12252}
df20: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
df30: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
df40: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
df50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
df60: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
df70: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
df80: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
df90: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
dfa0: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
dfb0: 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72           is unpr
dfc0: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
dfd0: 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
dfe0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
dff0: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
e000: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e010: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
e020: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
e030: 46 31 32 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12260}.**.** Th
e040: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
e050: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
e060: 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
e070: 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a  used by INSERT,.
e080: 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  ** UPDATE or DEL
e090: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73  ETE statements s
e0a0: 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
e0b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
e0c0: 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68  as opened..** Th
e0d0: 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73  e count includes
e0e0: 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f   all changes fro
e0f0: 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f  m all trigger co
e100: 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72  ntexts.  However
e110: 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
e120: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
e130: 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
e140: 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43  implement REPLAC
e150: 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  E constraints,.*
e160: 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
e170: 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
e180: 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c  ng, or DROP tabl
e190: 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a  e processing..**
e1a0: 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65   The changes are
e1b0: 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
e1c0: 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
e1d0: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
e1e0: 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  m is.** complete
e1f0: 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
e200: 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20  ement handle is 
e210: 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
e220: 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
e230: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
e240: 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
e250: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
e260: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
e270: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
e280: 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45   without a WHERE
e290: 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72   clause.** by dr
e2a0: 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
e2b0: 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
e2c0: 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20    (This is much 
e2d0: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
e2e0: 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
e2f0: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
e300: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
e310: 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  om the table.)  
e320: 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  Because of this.
e330: 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  ** optimization,
e340: 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69   the deletions i
e350: 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  n "DELETE FROM t
e360: 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f  able" are not ro
e370: 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a  w changes and.**
e380: 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75   will not be cou
e390: 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  nted by the sqli
e3a0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72  te3_changes() or
e3b0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
e3c0: 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75  changes()].** fu
e3d0: 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c  nctions, regardl
e3e0: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
e3f0: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
e400: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
e410: 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62  ly.** in the tab
e420: 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61  le.  To get an a
e430: 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
e440: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
e450: 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
e460: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
e470: 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
e480: 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53  instead..**.** S
e490: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
e4a0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
e4b0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
e4c0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
e4d0: 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20  ** {F12261} The 
e4e0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
e4f0: 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e  hanges()] return
e500: 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
e510: 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
e520: 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
e530: 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20  used by INSERT, 
e540: 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44  UPDATE, and/or D
e550: 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20  ELETE.**        
e560: 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20    statements on 
e570: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
e580: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
e590: 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20  in any.**       
e5a0: 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
e5b0: 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61  xt, since the da
e5c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e5d0: 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a  n was created..*
e5e0: 2a 0a 2a 2a 20 7b 46 31 32 32 36 33 7d 20 53 74  *.** {F12263} St
e5f0: 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20  atements of the 
e600: 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f  form "DELETE FRO
e610: 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74  M tablename" wit
e620: 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  h no.**         
e630: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68   WHERE clause sh
e640: 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  all not change t
e650: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
e660: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
e670: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
e680: 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a  changes()]..**.*
e690: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
e6a0: 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66  *.** {U12264} If
e6b0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
e6c0: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
e6d0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
e6e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e6f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
e700: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
e710: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
e720: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
e730: 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20   value .**      
e740: 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 20      returned is 
e750: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
e760: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
e770: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
e780: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
e790: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
e7a0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
e7b0: 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
e7c0: 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32 32 37  ing Query {F1227
e7d0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
e7e0: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
e7f0: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
e800: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
e810: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
e820: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
e830: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
e840: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
e850: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
e860: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
e870: 20 74 6f 20 61 6e 20 75 73 65 72 20 61 63 74 69   to an user acti
e880: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
e890: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
e8a0: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
e8b0: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
e8c0: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
e8d0: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
e8e0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
e8f0: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
e900: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
e910: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
e920: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
e930: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
e940: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
e950: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
e960: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
e970: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
e980: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
e990: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
e9a0: 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
e9b0: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
e9c0: 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
e9d0: 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
e9e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
e9f0: 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
ea00: 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f  *.** If an SQL o
ea10: 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
ea20: 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
ea30: 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
ea40: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
ea50: 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
ea60: 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
ea70: 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
ea80: 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
ea90: 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
eaa0: 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
eab0: 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
eac0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  .**.** An SQL op
ead0: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
eae0: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
eaf0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
eb00: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
eb10: 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
eb20: 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
eb30: 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
eb40: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
eb50: 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
eb60: 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
eb70: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
eb80: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
eb90: 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
eba0: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
ebb0: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
ebc0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ebd0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ebe0: 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
ebf0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
ec00: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
ec10: 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  rted after sqlit
ec20: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
ec30: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  eturns..**.** IN
ec40: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
ec50: 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71  {F12271} The [sq
ec60: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ec70: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
ec80: 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e  l force all runn
ec90: 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
eca0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
ecb0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
ecc0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
ecd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
ece0: 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20          to halt 
ecf0: 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67  after processing
ed00: 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64   at most one add
ed10: 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64  itional row of d
ed20: 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ata..**.** {F122
ed30: 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74  72} Any SQL stat
ed40: 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e  ement that is in
ed50: 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71  terrupted by [sq
ed60: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ed70: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
ed80: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
ed90: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
eda0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
edb0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d  :.**.** {U12279}
edc0: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
edd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
ede0: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
edf0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
ee00: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75  *          is ru
ee10: 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
ee20: 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
ee30: 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
ee40: 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
ee50: 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
ee60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ee70: 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
ee80: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
ee90: 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35 31   Complete {F1051
eea0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
eeb0: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
eec0: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
eed0: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
eee0: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
eef0: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
ef00: 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
ef10: 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61   form complete a
ef20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
ef30: 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
ef40: 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
ef50: 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
ef60: 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
ef70: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
ef80: 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
ef90: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72  utines return tr
efa0: 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  ue if the input 
efb0: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
efc0: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
efd0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
efe0: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
eff0: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
f000: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
f010: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
f020: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
f030: 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65   is not a fragme
f040: 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54  nt of a.** CREAT
f050: 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
f060: 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73  ent.  Semicolons
f070: 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
f080: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
f090: 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
f0a0: 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
f0b0: 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
f0c0: 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
f0d0: 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
f0e0: 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
f0f0: 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
f100: 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
f110: 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
f120: 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
f130: 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
f140: 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  t terminator..**
f150: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
f160: 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
f170: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
f180: 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
f190: 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
f1a0: 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
f1b0: 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ct SQL..**.** IN
f1c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
f1d0: 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c  {F10511} The sql
f1e0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20  ite3_complete() 
f1f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
f200: 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f  lete16() functio
f210: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ns.**          r
f220: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
f230: 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c  zero) if and onl
f240: 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f  y if the last no
f250: 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20  n-whitespace.** 
f260: 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69           token i
f270: 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
f280: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
f290: 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77  t is not in betw
f2a0: 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
f2b0: 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
f2c0: 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
f2d0: 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
f2e0: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
f2f0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31  NS:.**.** {U1051
f300: 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  2} The input to 
f310: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f320: 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  () must be a zer
f330: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
f340: 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
f350: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  tring..**.** {U1
f360: 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
f370: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  to sqlite3_compl
f380: 65 74 65 31 36 28 29 20 6d 75 73 74 20 62 65 20  ete16() must be 
f390: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
f3a0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
f3b0: 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
f3c0: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
f3d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f3e0: 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
f3f0: 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
f400: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f410: 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
f420: 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
f430: 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
f440: 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
f450: 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
f460: 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a  Errors {F12310}.
f470: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
f480: 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
f490: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
f4a0: 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
f4b0: 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
f4c0: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
f4d0: 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
f4e0: 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
f4f0: 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
f500: 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
f510: 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  locked..**.** If
f520: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
f530: 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
f540: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
f550: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
f560: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
f570: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
f580: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
f590: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
f5a0: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
f5b0: 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
f5c0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
f5d0: 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
f5e0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
f5f0: 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
f600: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f610: 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
f620: 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
f630: 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
f640: 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
f650: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
f660: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
f670: 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65  _handler().  The
f680: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f690: 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
f6a0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
f6b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
f6c0: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
f6d0: 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
f6e0: 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
f6f0: 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
f700: 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ent.  If the.** 
f710: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
f720: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
f730: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
f740: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
f750: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
f760: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
f770: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
f780: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
f790: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
f7a0: 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
f7b0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
f7c0: 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
f7d0: 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
f7e0: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
f7f0: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
f800: 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
f810: 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
f820: 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
f830: 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
f840: 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
f850: 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
f860: 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
f870: 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
f880: 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
f890: 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
f8a0: 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
f8b0: 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
f8c0: 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
f8d0: 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
f8e0: 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
f8f0: 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
f900: 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
f910: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
f920: 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
f930: 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
f940: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
f950: 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
f960: 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
f970: 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
f980: 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
f990: 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
f9a0: 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
f9b0: 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
f9c0: 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
f9d0: 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
f9e0: 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
f9f0: 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
fa00: 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
fa10: 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
fa20: 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
fa30: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
fa40: 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
fa50: 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
fa60: 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
fa70: 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
fa80: 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
fa90: 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
faa0: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
fab0: 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
fac0: 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
fad0: 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
fae0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
faf0: 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
fb00: 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
fb10: 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
fb20: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
fb30: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
fb40: 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
fb50: 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
fb60: 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
fb70: 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
fb80: 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
fb90: 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
fba0: 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
fbb0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
fbc0: 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
fbd0: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
fbe0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
fbf0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
fc00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
fc10: 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
fc20: 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
fc30: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
fc40: 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
fc50: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
fc60: 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
fc70: 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
fc80: 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
fc90: 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
fca0: 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
fcb0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
fcc0: 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
fcd0: 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
fce0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
fcf0: 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
fd00: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
fd10: 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
fd20: 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
fd30: 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
fd40: 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
fd50: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
fd60: 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
fd70: 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
fd80: 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
fd90: 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
fda0: 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
fdb0: 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
fdc0: 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
fdd0: 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
fde0: 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
fdf0: 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
fe00: 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
fe10: 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
fe20: 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
fe30: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
fe40: 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
fe50: 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
fe60: 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
fe70: 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
fe80: 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
fe90: 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
fea0: 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
feb0: 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
fec0: 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
fed0: 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
fee0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
fef0: 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
ff00: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
ff10: 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
ff20: 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
ff30: 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
ff40: 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
ff50: 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rtant..**.** The
ff60: 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
ff70: 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
ff80: 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
ff90: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
ffa0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
ffb0: 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
ffc0: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
ffd0: 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
ffe0: 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
fff0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  .  Note that cal
10000 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
10010 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
10020 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
10030 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
10040 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
10050 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
10060 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b  * {F12311} The [
10070 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10080 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  dler()] function
10090 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 62 75   replaces the bu
100a0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20  sy handler.**   
100b0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
100c0 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
100d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
100e0 69 66 69 65 64 20 62 79 20 74 68 65 20 31 73 74  ified by the 1st
100f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
10100 61 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e 65  ameter with a ne
10110 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  w busy handler i
10120 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
10130 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20   2nd and 3rd.** 
10140 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
10150 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ers..**.** {F123
10160 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  12} The default 
10170 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
10180 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
10190 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c  nnections is NUL
101a0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34  L..**.** {F12314
101b0 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  } When two or mo
101c0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
101d0 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61 0a 2a  ection share a.*
101e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
101f0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
10200 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e  d_cache | common
10210 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20   cache],.**     
10220 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61       the busy ha
10230 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61  ndler for the da
10240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10250 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  n currently usin
10260 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
10270 65 20 63 61 63 68 65 20 69 73 20 69 6e 76 6f 6b  e cache is invok
10280 65 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68  ed when the cach
10290 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c  e encounters a l
102a0 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ock..**.** {F123
102b0 31 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61  16} If a busy ha
102c0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  ndler callback r
102d0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
102e0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
102f0 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
10300 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64     that provoked
10310 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65   the locking eve
10320 6e 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  nt will return [
10330 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
10340 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51 4c  .** {F12318} SQL
10350 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73  ite will invokes
10360 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10370 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
10380 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20  ents which.**   
10390 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70         are a cop
103a0 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72  y of the pointer
103b0 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
103c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
103d0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
103e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
103f0 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75  ler()] and a cou
10400 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
10410 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20   of prior.**    
10420 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
10430 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61  s of the busy ha
10440 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61  ndler for the sa
10450 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
10460 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
10470 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33  ONS:.**.** {U123
10480 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c  19} A busy handl
10490 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 6c  er should not cl
104a0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
104b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
104c0 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70          or [prep
104d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
104e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
104f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
10500 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
10510 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
10520 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
10530 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
10540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10550 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
10560 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a  out {F12340}.**.
10570 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10580 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
10590 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
105a0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
105b0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
105c0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
105d0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
105e0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
105f0 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
10600 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
10610 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
10620 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
10630 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
10640 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
10650 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
10660 46 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  F12343} After "m
10670 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
10680 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
10690 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
106a0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
106b0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
106c0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
106d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
106e0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
106f0 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
10700 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
10710 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
10720 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
10730 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
10740 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
10750 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
10760 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
10770 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
10780 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
10790 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
107a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
107b0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
107c0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
107d0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
107e0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
107f0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
10800 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10810 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
10820 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
10830 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
10840 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
10850 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
10860 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
10870 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20  .**.** {F12341} 
10880 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  The [sqlite3_bus
10890 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e  y_timeout()] fun
108a0 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65 73 20  ction overrides 
108b0 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20  any prior.**    
108c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
108d0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f  usy_timeout()] o
108e0 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  r [sqlite3_busy_
108f0 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69  handler()] setti
10900 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
10910 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
10920 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
10930 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49  **.** {F12343} I
10940 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
10950 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
10960 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
10970 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20  is less than.** 
10980 20 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61           or equa
10990 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20  l to zero, then 
109a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
109b0 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f 20 74   is cleared so t
109c0 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
109d0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c  all subsequent l
109e0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d  ocking events im
109f0 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e  mediately return
10a00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
10a10 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49  **.** {F12344} I
10a20 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
10a30 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
10a40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
10a50 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a  is a positive.**
10a60 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
10a70 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20   N, then a busy 
10a80 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74 20 74  handler is set t
10a90 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20 63  hat repeatedly c
10aa0 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  alls.**         
10ab0 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
10ac0 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46 53 20  thod in the VFS 
10ad0 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69 6c 20  interface until 
10ae0 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 20 20  either the.**   
10af0 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61         lock clea
10b00 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  rs or until the 
10b10 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70  cumulative sleep
10b20 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64 20 62   time reported b
10b30 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
10b40 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63 65  by xSleep() exce
10b50 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e  eds N millisecon
10b60 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
10b70 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
10b80 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
10b90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10ba0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
10bb0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
10bc0 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 46 31  ning Queries {F1
10bd0 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69  2370}.**.** Defi
10be0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
10bf0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
10c00 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
10c10 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
10c20 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
10c30 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
10c40 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
10c50 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
10c60 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
10c70 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
10c80 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
10c90 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
10ca0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
10cb0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
10cc0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
10cd0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
10ce0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
10cf0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
10d00 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10d10 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
10d20 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
10d30 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
10d40 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
10d50 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
10d60 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
10d70 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
10d80 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
10d90 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
10da0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
10db0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
10dc0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
10dd0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
10de0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
10df0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
10e00 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
10e10 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
10e20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
10e30 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
10e40 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
10e50 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
10e60 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
10e70 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
10e80 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
10e90 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
10ea0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
10eb0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
10ec0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
10ed0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
10ee0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
10ef0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
10f00 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
10f10 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
10f20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
10f30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
10f40 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
10f50 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
10f60 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
10f70 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
10f80 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
10f90 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
10fa0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
10fb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
10fc0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
10fd0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
10fe0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
10ff0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11000 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
11010 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
11020 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
11030 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
11040 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
11050 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
11060 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
11070 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
11080 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
11090 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
110a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
110b0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
110c0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
110d0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
110e0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
110f0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
11100 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
11110 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
11120 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
11130 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
11140 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
11150 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
11160 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
11170 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
11180 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
11190 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
111a0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
111b0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
111c0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
111d0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
111e0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
111f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11200 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
11210 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
11220 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11230 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
11240 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
11250 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
11260 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
11270 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11280 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
11290 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
112a0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
112b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
112c0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
112d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
112e0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
112f0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
11300 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
11310 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
11320 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
11330 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11340 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
11350 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
11360 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
11370 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
11380 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
11390 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
113a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
113b0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
113c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
113d0 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
113e0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
113f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
11400 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
11410 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
11420 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
11430 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
11440 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
11450 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
11460 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f  d.** pass the po
11470 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73  inter to the res
11480 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c  ult table to sql
11490 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
114a0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
114b0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
114c0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
114d0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
114e0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
114f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
11500 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
11510 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
11520 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
11530 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
11540 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
11550 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
11560 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
11570 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
11580 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
11590 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
115a0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
115b0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
115c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
115d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
115e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
115f0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
11600 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
11610 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
11620 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
11630 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
11640 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
11650 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
11660 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
11670 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
11680 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
11690 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
116a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
116b0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
116c0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
116d0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
116e0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
116f0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
11700 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
11710 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
11720 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
11730 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
11740 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
11750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
11760 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ode()] or [sqlit
11770 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
11780 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
11790 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49  **.** {F12371} I
117a0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  f a [sqlite3_get
117b0 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20  _table()] fails 
117c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
117d0 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ion, then.**    
117e0 20 20 20 20 20 20 69 74 20 66 72 65 65 73 20 74        it frees t
117f0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11800 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69  under constructi
11810 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68 65 0a 2a  on, aborts the.*
11820 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79  *          query
11830 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69   in process, ski
11840 70 73 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ps any subsequen
11850 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 73 20  t queries, sets 
11860 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
11870 2a 72 65 73 75 6c 74 70 20 6f 75 74 70 75 74 20  *resultp output 
11880 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20  pointer to NULL 
11890 61 6e 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  and returns [SQL
118a0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
118b0 2a 20 7b 46 31 32 33 37 33 7d 20 49 66 20 74 68  * {F12373} If th
118c0 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65  e ncolumn parame
118d0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
118e0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  get_table()] is 
118f0 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  not NULL.**     
11900 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
11910 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
11920 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65  writes the numbe
11930 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
11940 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
11950 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
11960 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e 63  e query into *nc
11970 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71 75 65  olumn if the que
11980 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  ry is.**        
11990 20 20 73 75 63 63 65 73 73 66 75 6c 20 28 69 66    successful (if
119a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
119b0 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29  turns SQLITE_OK)
119c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d  ..**.** {F12374}
119d0 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70 61 72   If the nrow par
119e0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
119f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
11a00 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
11a10 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
11a20 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
11a30 29 5d 20 77 72 69 74 65 73 20 74 68 65 20 6e 75  )] writes the nu
11a40 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20  mber of rows in 
11a50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
11a60 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
11a70 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e 72  e query into *nr
11a80 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ow if the query 
11a90 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  is.**          s
11aa0 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68  uccessful (if th
11ab0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
11ac0 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a  ns SQLITE_OK)..*
11ad0 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 54 68  *.** {F12376} Th
11ae0 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  e [sqlite3_get_t
11af0 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  able()] function
11b00 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c 75   sets its *ncolu
11b10 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 68 65 0a  mn value to the.
11b20 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
11b30 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
11b40 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
11b50 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20  of the query in 
11b60 74 68 65 20 73 71 6c 0a 2a 2a 20 20 20 20 20 20  the sql.**      
11b70 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f      parameter, o
11b80 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68 65  r to zero if the
11b90 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68 61   query in sql ha
11ba0 73 20 61 6e 20 65 6d 70 74 79 20 72 65 73 75 6c  s an empty resul
11bb0 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  t set..*/.int sq
11bc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
11bd0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
11be0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
11bf0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
11c00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
11c10 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  l,      /* SQL t
11c20 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
11c30 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52 65 73  /.  char ***pRes
11c40 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52 65 73  ult,      /* Res
11c50 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
11c60 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77  y */.  int *nrow
11c70 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
11c80 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
11c90 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
11ca0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f  re */.  int *nco
11cb0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a  lumn,         /*
11cc0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
11cd0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
11ce0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
11cf0 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
11d00 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
11d10 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
11d20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
11d30 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
11d40 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
11d50 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
11d60 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
11d70 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ting Functions {
11d80 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17400}.**.** Th
11d90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
11da0 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74   workalikes of t
11db0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
11dc0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
11dd0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
11de0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
11df0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
11e00 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
11e10 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
11e20 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
11e30 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
11e40 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
11e50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
11e60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11e70 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
11e80 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
11e90 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
11ea0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
11eb0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
11ec0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20 42 6f  e3_free()].   Bo
11ed0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
11ee0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
11ef0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
11f00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
11f10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
11f20 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
11f30 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
11f40 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
11f50 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
11f60 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
11f70 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
11f80 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
11f90 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
11fa0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
11fb0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
11fc0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
11fd0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
11fe0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
11ff0 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
12000 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
12010 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
12020 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
12030 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
12040 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
12050 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
12060 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
12070 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69  rintf().  This i
12080 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
12090 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
120a0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
120b0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
120c0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
120d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e  ompatibility.  N
120e0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
120f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12100 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
12110 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
12120 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
12130 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
12140 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
12150 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
12160 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65   the buffer.  We
12170 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
12180 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
12190 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
121a0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
121b0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
121c0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
121d0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
121e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
121f0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
12200 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
12210 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
12220 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
12230 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  * As long as the
12240 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
12250 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
12260 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
12270 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
12280 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
12290 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
122a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
122b0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
122c0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
122d0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
122e0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
122f0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
12300 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
12310 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
12320 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
12330 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
12340 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
12350 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
12360 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
12370 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
12380 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
12390 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
123a0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
123b0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
123c0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
123d0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
123e0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
123f0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
12400 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
12410 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
12420 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
12430 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
12440 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
12450 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
12460 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
12470 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
12480 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
12490 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
124a0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
124b0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
124c0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
124d0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
124e0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
124f0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
12500 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
12510 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
12520 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
12530 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
12540 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
12550 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
12560 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
12570 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
12580 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
12590 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
125a0 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
125b0 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
125c0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
125d0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
125e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
125f0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
12600 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
12610 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
12620 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
12630 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
12640 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
12650 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
12660 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
12670 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12680 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
12690 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
126a0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
126b0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
126c0 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
126d0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
126e0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
126f0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
12700 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
12710 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12720 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
12730 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
12740 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
12750 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
12760 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
12770 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
12780 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
12790 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
127a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
127b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
127c0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
127d0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
127e0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
127f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
12800 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
12810 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
12820 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
12830 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
12840 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
12850 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
12860 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
12870 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
12880 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
12890 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
128a0 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
128b0 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
128c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
128d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
128e0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
128f0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
12900 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
12910 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
12920 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
12930 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
12940 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
12950 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
12960 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
12970 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
12980 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
12990 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
129a0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
129b0 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
129c0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
129d0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
129e0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
129f0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
12a00 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
12a10 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
12a20 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
12a30 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
12a40 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
12a50 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e  ingle quotes) in
12a60 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51   place of the %Q
12a70 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20   option. {END}  
12a80 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
12a90 0a 2a 2a 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  .** one could sa
12aa0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
12ab0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
12ac0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
12ad0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
12ae0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
12af0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
12b00 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
12b10 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
12b20 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
12b30 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
12b40 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12b50 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
12b60 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
12b70 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
12b80 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
12b90 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
12ba0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
12bb0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
12bc0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
12bd0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
12be0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
12bf0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
12c00 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
12c10 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
12c20 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
12c30 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
12c40 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
12c50 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
12c60 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
12c70 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
12c80 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
12c90 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
12ca0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
12cb0 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20  **.** {F17403}  
12cc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  The [sqlite3_mpr
12cd0 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c  intf()] and [sql
12ce0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d  ite3_vmprintf()]
12cf0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20   interfaces.**  
12d00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
12d10 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20  either pointers 
12d20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
12d30 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
12d40 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20   held in.**     
12d50 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74        memory obt
12d60 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
12d70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
12d80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69   NULL pointers i
12d90 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
12da0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
12db0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c  3_malloc()] fail
12dc0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36  s..**.** {F17406
12dd0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
12de0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
12df0 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a  rface writes a z
12e00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
12e10 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  *           UTF-
12e20 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68  8 string into th
12e30 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64  e buffer pointed
12e40 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
12e50 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  d parameter.**  
12e60 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65           provide
12e70 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74  d that the first
12e80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72   parameter is gr
12e90 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e  eater than zero.
12ea0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20  .**.** {F17407} 
12eb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
12ec0 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
12ed0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69  ace does not wri
12ee0 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20  te slots of.**  
12ef0 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74           its out
12f00 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20  put buffer (the 
12f10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12f20 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61  ) outside the ra
12f30 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
12f40 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d   of 0 through N-
12f50 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68  1 (where N is th
12f60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12f70 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r).**           
12f80 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
12f90 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
12fa0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
12fb0 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79      requested by
12fc0 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63   the format spec
12fd0 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68  ification..*/.ch
12fe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
12ff0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
13000 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
13010 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
13020 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
13030 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
13040 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
13050 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
13060 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
13070 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
13080 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
13090 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a  stem {F17300}.**
130a0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
130b0 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20  ore  uses these 
130c0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
130d0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
130e0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
130f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13100 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
13110 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
13120 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
13130 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
13140 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
13150 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
13160 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
13170 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
13180 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
13190 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
131a0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
131b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
131c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
131d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
131e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
131f0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
13200 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
13210 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
13220 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
13230 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ter..** If sqlit
13240 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
13250 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
13260 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
13270 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
13280 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
13290 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61  nter.  If the pa
132a0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
132b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
132c0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
132d0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
132e0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
132f0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
13300 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  nter..**.** Call
13310 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
13320 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
13330 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
13340 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
13350 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
13360 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13370 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
13380 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
13390 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
133a0 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  used.  The sqlit
133b0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
133c0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
133d0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
133e0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
133f0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
13400 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
13410 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
13420 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
13430 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
13440 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
13450 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
13460 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
13470 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
13480 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
13490 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
134a0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
134b0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
134c0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
134d0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
134e0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
134f0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
13500 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
13510 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
13520 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
13530 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
13540 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
13550 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
13560 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
13570 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
13580 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
13590 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a  e3_free()..**.**
135a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
135b0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
135c0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
135d0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
135e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
135f0 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
13600 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
13610 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
13620 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
13630 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13640 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
13650 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
13660 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
13670 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13680 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
13690 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
136a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
136b0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
136c0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
136d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
136e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
136f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
13700 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
13710 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13720 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
13730 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
13740 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
13750 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
13760 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
13770 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
13780 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
13790 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
137a0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
137b0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
137c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
137d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
137e0 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ()..** sqlite3_r
137f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
13800 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
13810 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13820 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
13830 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
13840 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
13850 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
13860 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
13870 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
13880 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
13890 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
138a0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
138b0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
138c0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
138d0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
138e0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
138f0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
13900 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13910 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
13920 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
13930 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
13940 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
13950 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
13960 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
13970 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
13980 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
13990 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
139a0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
139b0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
139c0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
139d0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
139e0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
139f0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
13a00 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
13a10 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
13a20 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65  tation of the me
13a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13a40 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a  subsystem uses.*
13a50 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  * the malloc(), 
13a60 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
13a70 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
13a80 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
13a90 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 46 31 37  library..** {F17
13aa0 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
13ab0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13ac0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13ad0 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
13ae0 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20  ZE=<i>NNN</i> C 
13af0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
13b00 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e  ro (where <i>NNN
13b10 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  </i>.** is an in
13b20 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c  teger), then SQL
13b30 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
13b40 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20  tic array of at 
13b50 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c  least.** <i>NNN<
13b60 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
13b70 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  e and uses that 
13b80 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66  array for all of
13b90 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20   its dynamic.** 
13ba0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13bb0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
13bc0 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  Additional memor
13bd0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
13be0 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64  ons.** may be ad
13bf0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13c00 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
13c10 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
13c20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
13c30 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
13c40 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
13c50 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
13c60 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
13c70 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
13c80 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
13c90 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
13ca0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
13cb0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
13cc0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
13cd0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
13ce0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
13cf0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
13d00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
13d10 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
13d20 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
13d30 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
13d40 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
13d50 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
13d60 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
13d70 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
13d80 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
13d90 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
13da0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
13db0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
13dc0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
13dd0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
13de0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
13df0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
13e00 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
13e10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13e20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
13e30 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
13e40 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
13e50 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
13e60 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
13e70 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
13e80 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
13e90 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
13ea0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
13eb0 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b   {F17303}  The [
13ec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
13ed0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
13ee0 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
13ef0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
13f00 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68        a newly ch
13f10 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20  ecked-out block 
13f20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
13f30 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  tes of memory.**
13f40 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
13f50 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
13f60 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73  d, or it returns
13f70 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75   NULL if it is u
13f80 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
13f90 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68     to fulfill th
13fa0 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a  e request..**.**
13fb0 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b   {F17304}  The [
13fc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
13fd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
13fe0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
13ff0 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ter if.**       
14000 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68      N is less th
14010 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
14020 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ero..**.** {F173
14030 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  05}  The [sqlite
14040 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72  3_free(P)] inter
14050 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65  face releases me
14060 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a  mory previously.
14070 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
14080 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
14090 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
140a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
140b0 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
140c0 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61     making it ava
140d0 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65  ilable for reuse
140e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36 7d  ..**.** {F17306}
140f0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
14100 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d  ite3_free(NULL)]
14110 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
14120 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  o-op..**.** {F17
14130 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  310}  A call to 
14140 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14150 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61  (0,N)] is equiva
14160 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
14170 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
14180 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
14190 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
141a0 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  2}  A call to [s
141b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
141c0 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,0)] is equivale
141d0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
141e0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
141f0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a  lite3_free(P)]..
14200 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20  **.** {F17315}  
14210 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
14220 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61  uses [sqlite3_ma
14230 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
14240 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
14250 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b             and [
14260 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
14270 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  for all of its m
14280 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14290 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
142a0 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e    deallocation n
142b0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  eeds..**.** {F17
142c0 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  318}  The [sqlit
142d0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
142e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
142f0 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
14300 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
14310 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63   to a block of c
14320 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72  hecked-out memor
14330 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  y of at least N 
14340 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a  bytes in size.**
14350 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
14360 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
14370 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  d, or a NULL poi
14380 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  nter..**.** {F17
14390 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  321}  When [sqli
143a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
143b0 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
143c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
143d0 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
143e0 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66      copies the f
143f0 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20  irst K bytes of 
14400 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69  content from P i
14410 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a  nto the newly.**
14420 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63             alloc
14430 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72  ated block, wher
14440 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65  e K is the lesse
14450 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73  r of N and the s
14460 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ize of.**       
14470 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20 50      the buffer P
14480 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d  ..**.** {F17322}
14490 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
144a0 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
144b0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
144c0 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
144d0 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
144e0 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66  releases the buf
144f0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fer P..**.** {F1
14500 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7323}  When [sql
14510 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
14520 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  )] returns NULL,
14530 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73   the buffer P is
14540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
14550 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65  t modified or re
14560 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49  leased..**.** LI
14570 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
14580 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20 70   {U17350}  The p
14590 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
145a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
145b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
145c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
145d0 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62            must b
145e0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
145f0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
14600 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
14610 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
14620 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20    invocation of 
14630 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14640 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
14650 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
14660 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
14670 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
14680 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55  leased..**.** {U
14690 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c  17351}  The appl
146a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
146b0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
146c0 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a 2a 20 20  ny part of .**  
146d0 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b           a block
146e0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
146f0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
14700 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eased using.**  
14710 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
14720 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
14730 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14740 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
14750 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
14760 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
14770 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
14780 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
14790 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
147a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
147b0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
147c0 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37  tatistics {F1737
147d0 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
147e0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
147f0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
14800 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
14810 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
14820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
14830 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
14840 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
14850 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14860 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
14870 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
14880 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
14890 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
148a0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  em..**.** INVARI
148b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
148c0 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  371} The [sqlite
148d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
148e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
148f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
14900 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
14910 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
14920 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
14930 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 6d   .**          (m
14940 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
14950 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  freed)..**.** {F
14960 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  17373} The [sqli
14970 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
14980 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
14990 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
149a0 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mum.**          
149b0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
149c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
149d0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
149e0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
149f0 20 20 20 20 20 20 20 77 61 73 20 6c 61 73 74 20         was last 
14a00 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  reset..**.** {F1
14a10 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73  7374} The values
14a20 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
14a30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14a40 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  d()] and.**     
14a50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
14a60 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14a70 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
14a80 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20  erhead.**       
14a90 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69     added by SQLi
14aa0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
14ab0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
14ac0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
14ad0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20  **          but 
14ae0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
14af0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
14b00 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
14b10 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20  library.**      
14b20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61      routines tha
14b30 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
14b40 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
14b50 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54  * .** {F17375} T
14b60 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
14b70 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
14b80 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
14b90 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  t value of.**   
14ba0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
14bb0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
14bc0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
14bd0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
14be0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
14bf0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
14c00 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
14c10 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
14c20 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
14c30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
14c40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
14c50 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
14c60 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
14c70 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68       prior to th
14c80 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
14c90 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
14ca0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
14cb0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
14cc0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
14cd0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
14ce0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
14cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
14d00 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
14d10 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37  r Generator {F17
14d20 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  390}.**.** SQLit
14d30 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
14d40 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
14d50 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
14d60 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
14d70 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
14d80 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
14d90 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
14da0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
14db0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
14dc0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
14dd0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
14de0 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
14df0 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
14e00 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
14e10 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
14e20 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
14e30 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
14e40 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
14e50 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
14e60 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
14e70 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
14e80 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
14e90 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
14ea0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
14eb0 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
14ec0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
14ed0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54  uffer P..**.** T
14ee0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
14ef0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
14f00 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
14f10 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
14f20 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
14f30 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
14f40 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
14f50 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
14f60 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
14f70 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
14f80 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
14f90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
14fa0 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75  ct..** On all su
14fb0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
14fc0 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
14fd0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
14fe0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
14ff0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
15000 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
15010 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
15020 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
15030 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  method..**.** IN
15040 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
15050 7b 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71  {F17392} The [sq
15060 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
15070 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  (N,P)] interface
15080 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20   writes N bytes 
15090 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  of.**          h
150a0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
150b0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
150c0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a  to buffer P..*/.
150d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
150e0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
150f0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
15100 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
15110 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
15120 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
15130 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12500}.**.** Th
15140 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
15150 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
15160 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
15170 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
15180 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15190 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
151a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
151b0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75  ument..** The au
151c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
151d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
151e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
151f0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
15200 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
15210 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
15220 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
15230 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
15240 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
15250 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
15260 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15270 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
15280 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
15290 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
152a0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
152b0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
152c0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
152d0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
152e0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
152f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15300 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
15310 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
15320 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
15330 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
15340 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
15350 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
15360 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
15370 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
15380 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
15390 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
153a0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
153b0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
153c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
153d0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
153e0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
153f0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
15400 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
15410 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
15420 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
15430 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
15440 2e 20 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  .   If the autho
15450 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
15460 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
15470 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
15480 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
15490 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
154a0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
154b0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   then [sqlite3_p
154c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
154d0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
154e0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
154f0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
15500 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
15510 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
15520 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
15530 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15540 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
15550 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
15560 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
15570 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
15580 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
15590 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
155a0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
155b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
155c0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
155d0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
155e0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
155f0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
15600 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
15610 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
15620 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
15630 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
15640 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15650 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
15660 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
15670 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15680 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
15690 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
156a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
156b0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
156c0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
156d0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
156e0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
156f0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
15700 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
15710 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
15720 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
15730 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
15740 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
15750 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
15760 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
15770 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
15780 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
15790 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
157a0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
157b0 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
157c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
157d0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
157e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
157f0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
15800 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15810 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
15820 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
15830 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68  interface..** Th
15840 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15850 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
15860 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
15870 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50   .** [SQLITE_COP
15880 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
15890 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
158a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
158b0 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61  ction.** to be a
158c0 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74  uthorized. The t
158d0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
158e0 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  th.** parameters
158f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
15900 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
15910 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
15920 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64  t contain .** ad
15930 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
15940 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
15950 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
15960 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ed..**.** An aut
15970 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
15980 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
15990 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
159a0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
159b0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
159c0 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65  rusted.** source
159d0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
159e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
159f0 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  nts do not try t
15a00 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a  o access data.**
15a10 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e   that they are n
15a20 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
15a30 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
15a40 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a  do not try to.**
15a50 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
15a60 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
15a70 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
15a80 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
15a90 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
15aa0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
15ab0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
15ac0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
15ad0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
15ae0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
15af0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
15b00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
15b10 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
15b20 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
15b30 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
15b40 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
15b50 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
15b60 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
15b70 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
15b80 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
15b90 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
15ba0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
15bb0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
15bc0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
15bd0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
15be0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
15bf0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
15c00 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
15c10 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
15c20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
15c30 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
15c40 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
15c50 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
15c60 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
15c70 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
15c80 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
15c90 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
15ca0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
15cb0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
15cc0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
15cd0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
15ce0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
15cf0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
15d00 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
15d10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
15d20 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
15d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15d40 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
15d50 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
15d60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
15d70 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
15d80 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
15d90 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20   call.  Disable 
15da0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
15db0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
15dc0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
15dd0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
15de0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
15df0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  efault..**.** No
15e00 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
15e10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15e20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
15e30 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  during .** [sqli
15e40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15e50 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
15e60 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
15e70 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
15e80 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
15e90 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
15ea0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
15eb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
15ec0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
15ed0 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  501} The [sqlite
15ee0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15ef0 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
15f00 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a  ce registers a.*
15f10 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
15f20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
15f30 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ith database con
15f40 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
15f50 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75   {F12502} The au
15f60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15f70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
15f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
15f90 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  re.**          b
15fa0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
15fb0 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20  .** {F12503} If 
15fc0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
15fd0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15fe0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
15ff0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
16000 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16010 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
16020 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
16030 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
16040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
16050 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
16060 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
16070 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20  hat caused.**   
16080 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f         the autho
16090 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74  rizer callback t
160a0 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c  o run shall fail
160b0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
160c0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
160d0 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  OR] error code a
160e0 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
160f0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
16100 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20  .**.** {F12504} 
16110 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
16120 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
16130 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
16140 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  , the operation.
16150 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63  **          desc
16160 72 69 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e  ribed is coded n
16170 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ormally..**.** {
16180 46 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65  F12505} When the
16190 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
161a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
161b0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
161c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
161d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
161e0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
161f0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
16200 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  d the.**        
16210 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
16220 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
16230 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20  ll fail.**      
16240 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c      with an [SQL
16250 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
16260 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72   code and an err
16270 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
16280 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e         explainin
16290 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73  g that access is
162a0 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   denied..**.** {
162b0 46 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61  F12506} If the a
162c0 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
162d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
162e0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
162f0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
16300 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51  callback) is [SQ
16310 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74  LITE_READ] and t
16320 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16330 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
16340 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
16350 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
16360 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
16370 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
16380 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
16390 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
163a0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
163b0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
163c0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
163d0 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
163e0 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
163f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
16400 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
16410 0a 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20  .** {F12507} If 
16420 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16430 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
16440 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16450 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
16460 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
16470 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
16480 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
16490 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
164a0 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
164b0 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
164c0 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
164d0 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
164e0 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b  _DENY]. .**.** {
164f0 46 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73  F12510} The firs
16500 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
16510 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16520 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
16530 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
16540 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16550 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
16560 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
16570 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  er()] interface.
16580 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20  .**.** {F12511} 
16590 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
165a0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
165b0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
165c0 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er .**          
165d0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
165e0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
165f0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
16600 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
16610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
16620 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
16630 2a 0a 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68  *.** {F12512} Th
16640 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
16650 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
16660 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16670 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
16680 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16690 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
166a0 6e 74 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20  ntain .**       
166b0 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65     additional de
166c0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
166d0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
166e0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
166f0 46 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c  F12520} Each cal
16700 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65  l to [sqlite3_se
16710 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
16720 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
16730 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72            any pr
16740 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c  eviously install
16750 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  ed authorizer..*
16760 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20  *.** {F12521} A 
16770 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20  NULL authorizer 
16780 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75  means that no au
16790 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20  thorization.**  
167a0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
167b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
167c0 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20  ** {F12522} The 
167d0 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a  default authoriz
167e0 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  er is NULL..*/.i
167f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
16800 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
16810 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
16820 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
16830 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
16840 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
16850 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
16860 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
16870 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
16880 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
16890 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20  er Return Codes 
168a0 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12590}.**.** T
168b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
168c0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
168d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
168e0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
168f0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
16900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
16910 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
16920 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
16930 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
16940 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
16950 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
16960 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
16970 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
16980 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16990 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
169a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
169b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
169c0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
169d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
169e0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
169f0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
16a00 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
16a10 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
16a20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
16a30 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
16a40 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
16a50 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
16a60 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
16a70 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16a80 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
16a90 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12550}.**.** 
16aa0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
16ab0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
16ac0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
16ad0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
16ae0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
16af0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
16b00 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20  horizer certain 
16b10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
16b20 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
16b30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16b40 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
16b50 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
16b60 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
16b70 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
16b80 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
16b90 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
16ba0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
16bb0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
16bc0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
16bd0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
16be0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
16bf0 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
16c00 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
16c10 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
16c20 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  ration is to be 
16c30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
16c40 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
16c50 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
16c60 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
16c70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
16c80 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
16c90 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
16ca0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
16cb0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
16cc0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
16cd0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16ce0 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20  meter.  The 5th 
16cf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16d00 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
16d10 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
16d20 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
16d30 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
16d40 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69  mp", .** etc.) i
16d50 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54  f applicable.  T
16d60 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
16d70 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16d80 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
16d90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
16da0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
16db0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
16dc0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
16dd0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
16de0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
16df0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
16e00 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
16e10 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74  ectly from .** t
16e20 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
16e30 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
16e40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  NTS:.**.** {F125
16e50 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  51} The second p
16e60 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a  arameter to an .
16e70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16e80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16e90 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
16ea0 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c   callback] is al
16eb0 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ways an integer.
16ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
16ed0 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
16ee0 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74  rizer code] that
16ef0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
16f00 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
16f10 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68     is being auth
16f20 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
16f30 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61  12552} The 3rd a
16f40 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
16f50 73 20 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20  s to the .**    
16f60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
16f70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
16f80 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
16f90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
16fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
16fb0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
16fc0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
16fd0 67 20 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20  g on which .**  
16fe0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16ff0 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
17000 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
17010 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
17020 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
17030 46 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  F12553} The 5th 
17040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17060 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17070 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
17080 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
17090 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
170a0 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62      of the datab
170b0 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d  ase (example: "m
170c0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74  ain", "temp", et
170d0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
170e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34  e..**.** {F12554
170f0 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65  } The 6th parame
17100 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
17110 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17120 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17140 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
17150 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17160 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
17170 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
17180 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
17190 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ble for.**      
171a0 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61      the access a
171b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
171c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
171d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
171e0 79 20 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20  y from .**      
171f0 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51      top-level SQ
17200 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
17210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17220 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17230 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
17240 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
17250 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
17260 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
17270 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
17280 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
17290 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
172a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
172b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
172c0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
172d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
172e0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
172f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17300 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
17310 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
17320 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
17330 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
17340 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17350 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
17360 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
17370 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17380 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17390 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
173a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
173b0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
173c0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
173d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
173e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
173f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
17400 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
17410 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
17420 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17430 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17440 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
17450 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
17460 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
17470 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17480 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17490 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
174a0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
174b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
174c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
174d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
174e0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
174f0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
17500 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
17510 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17530 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
17540 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
17550 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
17560 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17580 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
17590 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
175a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
175b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
175c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
175d0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
175e0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
175f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17600 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
17620 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
17630 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
17640 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17650 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17660 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17670 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
17680 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
17690 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
176a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
176b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
176c0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
176d0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
176e0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
176f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17700 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
17710 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
17720 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
17730 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
17740 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17750 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
17760 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
17770 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
17780 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17790 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
177a0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
177b0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
177c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
177d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
177e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
177f0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
17800 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
17810 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
17820 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
17830 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
17840 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
17850 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
17860 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17870 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
17880 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17890 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
178a0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
178b0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
178c0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
178d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
178e0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
178f0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
17900 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17910 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17920 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17930 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
17940 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
17950 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17960 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
17970 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17980 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
17990 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
179a0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
179b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
179c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
179d0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
179e0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
179f0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
17a00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a20 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
17a30 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
17a40 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
17a50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17a60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
17a70 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
17a80 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
17a90 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
17aa0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
17ac0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
17ad0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
17ae0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
17af0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17b00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17b10 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
17b20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
17b30 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
17b40 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
17b50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17b60 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
17b70 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
17b80 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
17b90 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
17ba0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
17bb0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
17bc0 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e  31   /* Function
17bd0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
17be0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17bf0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
17c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
17c10 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
17c20 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
17c30 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
17c40 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
17c50 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38  Functions {F1228
17c60 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
17c70 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
17c80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17c90 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
17ca0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
17cb0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
17cc0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
17cd0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
17ce0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
17cf0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
17d00 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
17d10 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
17d20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
17d30 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
17d40 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
17d50 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
17d60 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
17d70 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
17d80 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
17d90 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
17da0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17db0 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
17dc0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
17dd0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
17de0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
17df0 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
17e00 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
17e10 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
17e20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
17e30 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
17e40 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
17e50 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
17e60 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
17e70 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
17e80 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 63  er..** .** The c
17e90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17ea0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
17eb0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
17ec0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
17ed0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
17ee0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
17ef0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
17f00 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
17f10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
17f20 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
17f30 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
17f40 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
17f50 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
17f60 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
17f70 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
17f80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f   The sqlite3_pro
17f90 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75  file() API is cu
17fa0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
17fb0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
17fc0 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63  and.** is subjec
17fd0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
17fe0 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75  emoval in a futu
17ff0 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a  re release..**.*
18000 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65  * The trigger re
18010 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20  porting feature 
18020 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  of the trace cal
18030 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65  lback is conside
18040 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  red.** experimen
18050 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
18060 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
18070 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
18080 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46  e releases..** F
18090 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
180a0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  f SQLite might a
180b0 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63  lso add new trac
180c0 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69  e callback .** i
180d0 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  nvocations..**.*
180e0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
180f0 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65  .** {F12281} The
18100 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18110 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
18120 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
18130 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
18140 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51    whenever an SQ
18150 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  L statement firs
18160 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63  t begins to exec
18170 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ute and.**      
18180 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 74      whenever a t
18190 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
181a0 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  m first begins t
181b0 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  o run..**.** {F1
181c0 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20  2282} Each call 
181d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
181e0 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  e()] overrides t
181f0 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  he previously.**
18200 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
18210 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62  ered trace callb
18220 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ack..**.** {F122
18230 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65  83} A NULL trace
18240 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c   callback disabl
18250 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a  es tracing..**.*
18260 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20 66  * {F12284} The f
18270 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
18280 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
18290 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
182a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
182b0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
182c0 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  as the 3rd argum
182d0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
182e0 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  trace()]..**.** 
182f0 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65 63  {F12285} The sec
18300 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
18310 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
18320 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
18330 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
18340 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 20  ted UTF8 string 
18350 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f  containing the o
18360 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20  riginal text.** 
18370 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
18380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
18390 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69   it was passed i
183a0 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nto [sqlite3_pre
183b0 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20  pare_v2()].**   
183c0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71         or the eq
183d0 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20  uivalent, or an 
183e0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69  SQL comment indi
183f0 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e  cating the begin
18400 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
18410 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75   of a trigger su
18420 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20  bprogram..**.** 
18430 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c  {F12287} The cal
18440 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18450 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
18460 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
18470 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
18480 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20          as each 
18490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
184a0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nishes..**.** {F
184b0 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74  12288} The first
184c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
184d0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
184e0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
184f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
18500 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
18510 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
18520 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
18530 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  289} The second 
18540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18550 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
18560 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  k is a.**       
18570 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
18580 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
18590 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
185a0 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20  e complete text 
185b0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
185c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
185d0 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65   as it was proce
185e0 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ssed by [sqlite3
185f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
18600 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
18610 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a  e equivalent..**
18620 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65  .** {F12290} The
18630 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
18640 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
18650 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
18660 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20  estimate.**     
18670 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62       of the numb
18680 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
18690 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  s of wall-clock 
186a0 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f  time required to
186b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e  .**          run
186c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
186d0 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f  nt from start to
186e0 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64   finish..*/.void
186f0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
18700 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
18710 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
18720 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
18730 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
18740 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
18750 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
18760 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
18770 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
18780 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
18790 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
187a0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
187b0 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  s Callbacks {F12
187c0 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  910}.**.** This 
187d0 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
187e0 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
187f0 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
18800 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
18810 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
18820 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
18830 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
18840 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
18850 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
18860 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
18870 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
18880 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
18890 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  .   An example u
188a0 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
188b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
188c0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
188d0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
188e0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
188f0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
18900 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18910 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
18920 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
18930 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
18940 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
18950 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
18960 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
18970 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
18980 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
18990 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
189a0 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65  .** {F12911} The
189b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
189c0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
189d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
189e0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a  ss_handler()].**
189f0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
18a00 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
18a10 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
18a20 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
18a30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18a40 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
18a50 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20  ** {F12912} The 
18a60 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
18a70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
18a80 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
18a90 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  rtual.**        
18aa0 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65    machine opcode
18ab0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
18ac0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
18ad0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  t to .**        
18ae0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70    the [sqlite3_p
18af0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18b00 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67  )] call that reg
18b10 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
18b20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
18b30 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66  .  <todo>What if
18b40 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
18b50 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  1?</todo>.**.** 
18b60 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {F12913} The pro
18b70 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
18b80 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
18b90 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
18ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
18bb0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
18bc0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
18bd0 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  er()]..**.** {F1
18be0 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68  2914} The fourth
18bf0 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74   argument [sqlit
18c00 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
18c10 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20  ler()] is a.*** 
18c20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69          void poi
18c30 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
18c40 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
18c50 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
18c60 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
18c70 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
18c80 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35  d..**.** {F12915
18c90 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
18ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18cb0 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72  results in fewer
18cc0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
18cd0 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e    N opcodes bein
18ce0 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20  g executed,.**  
18cf0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
18d00 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
18d10 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
18d20 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a  ked. {END}.** .*
18d30 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79  * {F12916} Every
18d40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
18d50 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
18d60 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  er()].**        
18d70 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79    overwrites any
18d80 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
18d90 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73 20  stered progress 
18da0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  handler..**.** {
18db0 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70  F12917} If the p
18dc0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
18dd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
18de0 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73   then no progres
18df0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  s.**          ha
18e00 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  ndler is invoked
18e10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d  ..**.** {F12918}
18e20 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
18e30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18e40 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72  s a result other
18e50 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a   than 0, then.**
18e60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65            the be
18e70 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b  havior is a if [
18e80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18e90 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61  t()] had been ca
18ea0 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  lled..*/.void sq
18eb0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
18ec0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
18ed0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
18ee0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
18ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
18f00 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
18f10 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
18f20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12700}.**.** T
18f30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
18f40 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
18f50 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
18f60 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65   name.** is give
18f70 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d  n by the filenam
18f80 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  e argument..** T
18f90 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
18fa0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
18fb0 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20  ted as UTF-8.** 
18fc0 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
18fd0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
18fe0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
18ff0 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e   as UTF-16.** in
19000 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19010 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
19020 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
19030 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20  * An [sqlite3*] 
19040 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
19050 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  y returned in *p
19060 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
19070 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
19080 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
19090 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74  tion is if SQLit
190a0 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74  e is unable.** t
190b0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
190c0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
190d0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20  qlite3] object, 
190e0 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62  a NULL will.** b
190f0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
19100 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
19110 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
19120 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
19130 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  t..** If the dat
19140 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19150 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
19160 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
19170 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f  , then [SQLITE_O
19180 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
19190 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a   Otherwise an.**
191a0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
191b0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a  eturned.  The.**
191c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
191d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
191e0 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75  errmsg16()]  rou
191f0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
19200 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
19210 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
19220 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
19230 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
19240 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
19250 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
19260 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
19270 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71   UTF-8 if.** [sq
19280 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
19290 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
192a0 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61  2()] is called a
192b0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
192c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
192d0 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65  order if [sqlite
192e0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
192f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
19300 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
19310 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
19320 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
19330 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
19340 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73  ated with the [s
19350 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
19360 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
19370 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ed by passing it
19380 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
19390 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
193a0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
193b0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
193c0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
193d0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
193e0 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69  works like [sqli
193f0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20  te3_open()] .** 
19400 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
19410 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
19420 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
19430 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
19440 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
19450 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
19460 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
19470 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
19480 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20  r can be.** one 
19490 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  of:.**.** <ol>.*
194a0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
194b0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a  OPEN_READONLY].*
194c0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
194d0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a  OPEN_READWRITE].
194e0 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
194f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
19500 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
19510 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e  CREATE].** </ol>
19520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
19530 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65   value opens the
19540 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f   database read-o
19550 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20  nly. .** If the 
19560 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
19570 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69  t previously exi
19580 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
19590 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
195a0 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f   second option o
195b0 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  pens.** the data
195c0 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
195d0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
195e0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
195f0 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20  ding only if.** 
19600 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
19610 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20  rite protected. 
19620 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65 20   In either case 
19630 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
19640 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
19650 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69  st or an error i
19660 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
19670 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a   third option.**
19680 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
19690 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
196a0 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20  and writing and 
196b0 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74  creates it if it
196c0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72   does.** not alr
196d0 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54  eady exist..** T
196e0 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73  he third options
196f0 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61   is behavior tha
19700 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
19710 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
19720 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  en()].** and [sq
19730 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
19740 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
19750 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
19760 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19770 29 5d 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  )] is not one of
19780 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
19790 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
197a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
197b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
197c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
197d0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
197e0 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72  ry:", then an pr
197f0 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f  ivate.** in-memo
19800 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
19810 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
19820 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
19830 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
19840 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
19850 73 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  sh when the data
19860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19870 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
19880 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  re.** version of
19890 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61   SQLite might ma
198a0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
198b0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
198c0 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62  enames.** that b
198d0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
198e0 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74  " character.  It
198f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
19900 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20  that .** when a 
19910 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
19920 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65  e really does be
19930 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20  gin with.** ":" 
19940 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20  that you prefix 
19950 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
19960 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b  h a pathname lik
19970 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f  e "./" to.** avo
19980 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
19990 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
199a0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
199b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
199c0 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79  rivate temporary
199d0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
199e0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
199f0 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
19a00 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
19a10 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
19a20 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
19a30 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
19a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19a50 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
19a60 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
19a70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
19a80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
19a90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
19aa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
19ab0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
19ac0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
19ad0 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
19ae0 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
19af0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
19b00 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
19b10 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  se.  If the.** f
19b20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
19b30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
19b40 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
19b50 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
19b60 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73  .** object is us
19b70 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
19b80 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
19b90 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
19ba0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
19bb0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
19bc0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69  ment.** of [sqli
19bd0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
19be0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
19bf0 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d  ()] must be UTF-
19c00 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
19c10 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
19c20 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
19c30 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
19c40 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
19c50 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
19c60 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
19c70 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
19c80 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
19c90 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  them into.** [sq
19ca0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
19cb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
19cc0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
19cd0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
19ce0 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12701} The [sqli
19cf0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
19d00 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
19d10 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
19d20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
19d30 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
19d40 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20  create a new.** 
19d50 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
19d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
19d70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
19d80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64  *          the d
19d90 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76  atabase file giv
19da0 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73  en in their firs
19db0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
19dc0 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20  ** {F12702} The 
19dd0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19de0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
19df0 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20   as UTF-8.**    
19e00 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74        for [sqlit
19e10 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
19e20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19e30 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  )] and as UTF-16
19e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
19e50 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
19e60 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
19e70 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
19e80 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73  .** {F12703} A s
19e90 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
19ea0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
19eb0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
19ec0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a  e3_open16()], .*
19ed0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
19ee0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19ef0 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74  ] writes a point
19f00 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
19f10 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
19f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e  e connection] in
19f30 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20  to *ppDb..**.** 
19f40 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71  {F12704} The [sq
19f50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
19f60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19f70 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
19f80 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
19f90 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
19fa0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
19fb0 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73  _OK] upon succes
19fc0 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  s,.**          o
19fd0 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
19fe0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
19ff0 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
1a000 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66  {F12706} The def
1a010 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1a020 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1a030 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1a040 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1a050 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1a060 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1a070 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20  n_v2()] will be 
1a080 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
1a090 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c  2707} The defaul
1a0a0 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
1a0b0 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
1a0c0 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
1a0d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a0e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
1a0f0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a  will be UTF-16..
1a100 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54  **.** {F12709} T
1a110 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1a120 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  (F,D)] interface
1a130 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1a140 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
1a150 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1a160 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74  ,D,G,0)] where t
1a170 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69  he G parameter i
1a180 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
1a190 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a1a0 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50  RITE]|[SQLITE_OP
1a1b0 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a  EN_CREATE]..**.*
1a1c0 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68  * {F12711} If th
1a1d0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a1e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1a1f0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1a200 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1a210 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1a220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a230 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64  ONLY] then the d
1a240 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a250 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  d.**          fo
1a260 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a  r reading only..
1a270 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49  **.** {F12712} I
1a280 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a290 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a2a0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1a2b0 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1a2c0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1a2d0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1a2e0 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20  READWRITE] then 
1a2f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1a300 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
1a310 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77     reading and w
1a320 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1a330 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69  le, or for readi
1a340 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a  ng only if the.*
1a350 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20  *          file 
1a360 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1a370 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1a380 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a  ing system..**.*
1a390 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68  * {F12713} If th
1a3a0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a3b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
1a3c0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74  2(F,D,G,V)] omit
1a3d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1a3e0 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1a3f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1a400 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
1a410 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
1a420 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
1a430 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1a440 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1a450 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66  *.** {F12714} If
1a460 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1a470 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1a480 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n(v2(F,D,G,V)] c
1a490 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1a4a0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1a4b0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1a4c0 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1a4d0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1a4e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1a4f0 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74  viously exist, t
1a500 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hen an attempt i
1a510 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65  s made to create
1a520 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1a530 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
1a540 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
1a550 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20  {F12717} If the 
1a560 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a570 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
1a580 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1a590 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1a5a0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1a5b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
1a5c0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1a5d0 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a  n an private,.**
1a5e0 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1a5f0 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  ral, in-memory d
1a600 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
1a610 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1a620 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20  ction..**       
1a630 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
1a640 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
1a650 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a660 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
1a670 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
1a680 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
1a690 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
1a6a0 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c  2719} If the fil
1a6b0 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72  ename is NULL or
1a6c0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1a6d0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1a6e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1a6f0 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20  hemeral on-disk 
1a700 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1a710 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20   created..**    
1a720 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1a730 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1a740 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1a750 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1a760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1a770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a780 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1a790 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61  {F12721} The [da
1a7a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a7b0 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a  n] created by .*
1a7c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a7d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1a7e0 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74  G,V)] will use t
1a7f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1a800 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1a810 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62  ect identified b
1a820 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65  y the V paramete
1a830 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  r, or.**        
1a840 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73    the default [s
1a850 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1a860 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c  ct is V is a NUL
1a870 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1a880 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b 64   {F12723} Two [d
1a890 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a8a0 6f 6e 20 7c 20 64 61 74 61 62 61 73 65 20 63 6f  on | database co
1a8b0 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
1a8c0 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
1a8d0 61 63 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ache.**         
1a8e0 20 69 66 20 62 6f 74 68 20 77 65 72 65 20 6f 70   if both were op
1a8f0 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ened with the sa
1a900 6d 65 20 56 46 53 0a 2a 2a 20 20 20 20 20 20 20  me VFS.**       
1a910 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
1a920 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1a930 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63  cache | shared c
1a940 61 63 68 65 20 6d 6f 64 65 20 77 61 73 20 65 6e  ache mode was en
1a950 61 62 6c 65 64 5d 20 61 6e 64 0a 2a 2a 20 20 20  abled] and.**   
1a960 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66         if both f
1a970 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65  ilenames compare
1a980 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d   equal using mem
1a990 63 6d 70 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  cmp().**        
1a9a0 20 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 62    after having b
1a9b0 65 65 6e 20 70 72 6f 63 65 73 73 65 64 20 62 79  een processed by
1a9c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1a9d0 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  s | xFullPathnam
1a9e0 65 5d 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  e] method of.** 
1a9f0 20 20 20 20 20 20 20 20 20 74 68 65 20 56 46 53           the VFS
1aa00 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ..**.*/.int sqli
1aa10 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1aa20 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1aa30 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1aa40 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1aa50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1aa60 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1aa70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1aa80 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1aa90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1aaa0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1aab0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1aac0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1aad0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1aae0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1aaf0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1ab00 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ab10 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ab20 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1ab30 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ab40 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ab50 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ab60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ab70 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1ab80 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ab90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1aba0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1abb0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1abc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1abd0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1abe0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1abf0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1ac00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1ac10 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1ac20 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a  ssages {F12800}.
1ac30 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ac40 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1ac50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ac60 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
1ac70 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
1ac80 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
1ac90 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
1aca0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1acb0 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
1acc0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1acd0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1ace0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
1acf0 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
1ad00 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
1ad10 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1ad20 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20 74  all failed but t
1ad30 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
1ad40 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1ad50 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1ad60 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1ad70 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  te3_errcode().**
1ad80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1ad90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1ada0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1adb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1adc0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1add0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1ade0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1adf0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1ae00 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46  ther UTF8 or UTF
1ae10 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1ae20 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
1ae30 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1ae40 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1ae50 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1ae60 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1ae70 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1ae80 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69 74  eed to worry wit
1ae90 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  h freeing the re
1aea0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
1aeb0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
1aec0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
1aed0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
1aee0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
1aef0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1af00 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
1af10 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1af20 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
1af30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  NTS:.**.** {F128
1af40 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1af50 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74  _errcode(D)] int
1af60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1af70 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20  he numeric.**   
1af80 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
1af90 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
1afa0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1afb0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
1afc0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
1afd0 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20 20  sult code].**   
1afe0 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6d         for the m
1aff0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61 69  ost recently fai
1b000 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
1b010 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
1b020 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 5b            with [
1b030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b040 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
1b050 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  12803} The [sqli
1b060 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61  te3_errmsg(D)] a
1b070 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
1b080 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20  sg16(D)].**     
1b090 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
1b0a0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1b0b0 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61  anguage text tha
1b0c0 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20  t describes.**  
1b0d0 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f          the erro
1b0e0 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20  r in the mostly 
1b0f0 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20  recently failed 
1b100 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a  interface call,.
1b110 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f  **          enco
1b120 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54  ded as either UT
1b130 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
1b140 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
1b150 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {F12807} The str
1b160 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1b170 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b180 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1b190 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
1b1a0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1b1b0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
1b1c0 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
1b1d0 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
1b1e0 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  F12808} Calls to
1b1f0 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
1b200 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
1b210 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
1b220 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
1b230 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
1b240 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
1b250 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1b260 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
1b270 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
1b280 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1b290 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b2a0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1b2b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1b2c0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1b2d0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1b2e0 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {F12809} Interf
1b2f0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1b300 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1b310 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1b320 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1b330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1b340 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1b350 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1b360 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1b370 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1b380 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1b390 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1b3a0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1b3b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1b3c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b3d0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1b3e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1b3f0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1b400 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
1b410 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1b420 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1b430 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1b440 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1b450 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1b460 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1b470 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1b480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b490 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1b4a0 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a  ject {F13000}.**
1b4b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
1b4c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
1b4d0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1b4e0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
1b4f0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
1b500 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
1b510 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
1b520 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 0a  tatement.  This.
1b530 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  ** object is var
1b540 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1b550 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1b560 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20  ement" or a .** 
1b570 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1b580 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1b590 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1b5a0 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  nt"..** .** The 
1b5b0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
1b5c0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
1b5d0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
1b5e0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
1b5f0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
1b600 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1b610 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b620 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
1b630 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
1b640 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
1b650 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
1b660 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69  t parameters usi
1b670 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
1b680 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1b690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69  sqlite3_bind_* i
1b6a0 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c  nterfaces]..** <
1b6b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1b6c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1b6d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1b6e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1b6f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1b700 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1b710 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1b720 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1b730 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1b740 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1b750 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1b760 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1b770 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1b780 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1b790 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1b7a0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1b7b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1b7c0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1b7d0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1b7e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1b7f0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1b800 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1b810 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1b820 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1b830 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1b840 69 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a  imits {F12760}.*
1b850 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1b860 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1b870 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1b880 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1b890 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1b8a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1b8b0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1b8c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1b8d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1b8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b8f0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1b900 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1b910 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1b920 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1b930 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1b940 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1b950 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1b960 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1b970 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1b980 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1b990 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1b9a0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1b9b0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1b9c0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1b9d0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b9e0 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
1b9f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
1ba00 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1ba10 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1ba20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1ba30 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
1ba40 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
1ba50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
1ba60 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72  Z there is a har
1ba70 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64  d upper.** bound
1ba80 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1ba90 65 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63  e-time C-preproc
1baa0 65 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20  ess macro named 
1bab0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a  SQLITE_MAX_XYZ..
1bac0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1bad0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1bae0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1baf0 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
1bb00 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
1bb10 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
1bb20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1bb30 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
1bb40 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
1bb50 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
1bb60 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
1bb70 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1bb80 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1bb90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1bba0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1bbb0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1bbc0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1bbd0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1bbe0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1bbf0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1bc00 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1bc10 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1bc20 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1bc30 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1bc40 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61  bbrowser that ha
1bc50 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1bc60 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1bc70 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1bc80 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1bc90 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1bca0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1bcb0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1bcc0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1bcd0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1bce0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1bcf0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1bd00 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1bd10 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1bd20 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1bd30 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1bd40 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1bd50 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1bd60 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1bd70 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1bd80 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1bd90 20 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f   attach.  Develo
1bda0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1bdb0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1bdc0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1bdd0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1bde0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1bdf0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1be00 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1be10 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1be20 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1be30 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1be40 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1be50 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1be60 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1be70 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1be80 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1be90 61 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ace is currently
1bea0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1beb0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
1bec0 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68  subject.** to ch
1bed0 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20  ange or removal 
1bee0 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f  without prior no
1bef0 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tice..**.** INVA
1bf00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1bf10 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73  12762} A success
1bf20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1bf30 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1bf40 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a  )] where V is.**
1bf50 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69            positi
1bf60 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ve changes the.*
1bf70 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74  *          limit
1bf80 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1bf90 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b  construct C in [
1bfa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bfb0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
1bfc0 20 20 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72     to the lesser
1bfd0 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61   of V and the ha
1bfe0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  rd upper bound o
1bff0 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20  n the size.**   
1c000 20 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74         of C that
1c010 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69   is set at compi
1c020 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  le-time..**.** {
1c030 46 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73  F12766} A succes
1c040 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1c050 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1c060 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e  V)] where V is n
1c070 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
1c080 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73      leaves the s
1c090 74 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73  tate of [databas
1c0a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1c0b0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
1c0c0 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63 63   {F12769} A succ
1c0d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1c0e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
1c0f0 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
1c100 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
1c110 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
1c120 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1c130 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a  construct C in.*
1c140 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64  *          in [d
1c150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c160 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20  on] D as it was 
1c170 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c  prior to the cal
1c180 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1c190 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
1c1a0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
1c1b0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
1c1c0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1c1d0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
1c1e0 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45  s {F12790}.** KE
1c1f0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
1c200 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20  ategory} {limit 
1c210 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a  categories}.** .
1c220 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1c230 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
1c240 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b  s aspects of a [
1c250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c260 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e  ion].** that can
1c270 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73   be limited in s
1c280 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ize by calls to 
1c290 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1c2a0 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e  ]..** The meanin
1c2b0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
1c2c0 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20  s limits are as 
1c2d0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c2e0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
1c2f0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1c300 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c310 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1c320 6e 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ny.** string or 
1c330 62 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f  blob or table ro
1c340 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
1c350 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1c360 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1c370 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c380 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1c390 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1c3a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1c3b0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1c3c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c3d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c3e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1c3f0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1c400 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1c410 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
1c420 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  ECT or the maxim
1c430 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1c440 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1c450 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
1c460 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
1c470 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
1c480 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c490 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1c4a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c4b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1c4c0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1c4d0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1c4e0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
1c4f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c500 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
1c510 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c520 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c530 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
1c540 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
1c550 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
1c560 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c570 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
1c580 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c590 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
1c5a0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
1c5b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1c5c0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
1c5d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
1c5e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1c5f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c600 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1c610 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
1c620 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c630 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1c640 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
1c650 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
1c660 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1c670 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1c680 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c690 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68  number of attach
1c6a0 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64  ed databases.</d
1c6b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1c6c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1c6d0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1c6e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c6f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1c700 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1c710 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45  ment to the LIKE
1c720 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72   or.** GLOB oper
1c730 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ators.</dd>.**.*
1c740 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1c750 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c760 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1c770 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c780 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
1c790 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1c7a0 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
1c7b0 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a  e bound.</dd>.**
1c7c0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1c7d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1c7e0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1c7f0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1c800 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c810 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1c820 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1c830 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c840 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1c850 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1c860 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c870 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1c880 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1c890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c8a0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1c8b0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1c8c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c8d0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1c8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1c8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c900 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1c910 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1c920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c930 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1c940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c950 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1c960 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1c970 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1c980 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1c990 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1c9a0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1c9b0 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    9../*.** CAPI3
1c9c0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
1c9d0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1c9e0 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13010}.**.** T
1c9f0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
1ca00 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
1ca10 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
1ca20 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
1ca30 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
1ca40 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
1ca50 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a   routines. .**.*
1ca60 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1ca70 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20  ment "db" is an 
1ca80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ca90 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e  tion] .** obtain
1caa0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20  ed from a prior 
1cab0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1cac0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1cad0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a  e3_open_v2()].**
1cae0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1caf0 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20  n16()]. .** The 
1cb00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1cb10 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74  "zSql" is the st
1cb20 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1cb30 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
1cb40 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
1cb50 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
1cb60 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1cb70 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
1cb80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
1cb90 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73   interfaces uses
1cba0 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74   UTF-8 and sqlit
1cbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
1cbc0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1cbd0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
1cbe0 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a   UTF-16. {END}.*
1cbf0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
1cc00 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1cc10 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c  ss.** than zero,
1cc20 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
1cc30 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
1cc40 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1cc50 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20  or..** If nByte 
1cc60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1cc70 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
1cc80 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1cc90 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64  f .** bytes read
1cca0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
1ccb0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
1ccc0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
1ccd0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
1cce0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
1ccf0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
1cd00 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
1cd10 72 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79  r or .** the nBy
1cd20 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
1cd30 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
1cd40 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
1cd50 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
1cd60 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
1cd70 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
1cd80 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
1cd90 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
1cda0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
1cdb0 74 61 67 65 20 74 6f 20 62 65 20 68 61 64 20 62  tage to be had b
1cdc0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1cdd0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1cde0 74 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  t .** is equal t
1cdf0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
1ce00 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
1ce10 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
1ce20 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74  luding</i> .** t
1ce30 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
1ce40 72 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a  r bytes.{END}.**
1ce50 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  .** *pzTail is m
1ce60 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1ce70 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70  the first byte p
1ce80 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1ce90 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20  he.** first SQL 
1cea0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1ceb0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1cec0 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20  es only compile 
1ced0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61  the first.** sta
1cee0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1cef0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1cf00 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
1cf10 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75  hat remains.** u
1cf20 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1cf30 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
1cf40 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
1cf50 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
1cf60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1cf70 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
1cf80 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
1cf90 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
1cfa0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
1cfb0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1cfc0 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c  s.** set to NULL
1cfd0 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1cfe0 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1cff0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1d000 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70  ut.** is and emp
1d010 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
1d020 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1d030 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1d040 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d  ULL..** {U13018}
1d050 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1d060 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1d070 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1d080 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ng the.** compil
1d090 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1d0a0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
1d0b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1d0c0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1d0d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1d0e0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
1d0f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1d100 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1d110 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  ise an .** [erro
1d120 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1d130 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1d140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d150 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
1d160 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
1d170 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
1d180 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
1d190 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
1d1a0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
1d1b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1d1c0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
1d1d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d1e0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
1d1f0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
1d200 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
1d210 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1d220 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1d230 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1d240 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1d250 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1d260 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1d270 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1d280 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
1d290 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69   text. {END} Thi
1d2a0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
1d2b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
1d2c0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
1d2d0 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
1d2e0 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
1d2f0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1d300 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
1d310 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1d320 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1d330 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1d340 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1d350 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1d360 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1d370 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1d380 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1d390 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1d3a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1d3b0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1d3c0 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
1d3d0 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
1d3e0 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
1d3f0 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
1d400 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
1d410 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
1d420 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
1d430 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1d440 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
1d450 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
1d460 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20  y behavior, .** 
1d470 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d480 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  is now a fatal e
1d490 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a  rror.  Calling.*
1d4a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d4b0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
1d4c0 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
1d4d0 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
1d4e0 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
1d4f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d500 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
1d510 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
1d520 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
1d530 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
1d540 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
1d550 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f  urn. {END}.** </
1d560 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1d570 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
1d580 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c  occurs, .** [sql
1d590 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1d5a0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
1d5b0 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a  the detailed .**
1d5c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1d5d0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1d5e0 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68  r codes]. .** Th
1d5f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1d600 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69  r was that [sqli
1d610 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
1d620 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
1d630 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  generic.** [SQLI
1d640 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
1d650 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f   code and you wo
1d660 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1d670 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1d680 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
1d690 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  set()] in order 
1d6a0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1d6b0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1d6c0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20  the problem..** 
1d6d0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
1d6e0 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
1d6f0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1d700 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1d710 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
1d720 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1d730 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
1d740 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ol>.**.** INVARI
1d750 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1d760 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
1d770 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
1d780 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1d790 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1d7a0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1d7b0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
1d7c0 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
1d7d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
1d7e0 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
1d7f0 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
1d800 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  TF-8..**.** {F13
1d810 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  012} The [sqlite
1d820 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a  3_prepare16(db,z
1d830 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
1d840 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1d850 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1d860 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1d870 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1d880 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1d890 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1d8a0 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1d8b0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1d8c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1d8d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  er..**.** {F1301
1d8e0 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
1d8f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1d900 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d910 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
1d920 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1d930 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1d940 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1d950 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78  ro, then SQL tex
1d960 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
1d970 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
1d980 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1d990 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1d9a0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
1d9b0 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
1d9c0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1d9d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d9e0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1d9f0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1da00 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1da10 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
1da20 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
1da30 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
1da40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1da50 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
1da60 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
1da70 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  F13015} In [sqli
1da80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1da90 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
1daa0 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
1dab0 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
1dac0 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
1dad0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1dae0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
1daf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1db00 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
1db10 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
1db20 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1db30 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1db40 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
1db50 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
1db60 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1db70 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1db80 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
1db90 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1dba0 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
1dbb0 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
1dbc0 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
1dbd0 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
1dbe0 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75  ** {F13016} A su
1dbf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1dc00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dc10 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
1dc20 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
1dc30 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
1dc40 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
1dc50 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
1dc60 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
1dc70 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1dc80 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1dc90 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
1dca0 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20  ter to NULL.**  
1dcb0 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20          if zSql 
1dcc0 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
1dcd0 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
1dce0 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
1dcf0 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ts. .**.** {F130
1dd00 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1dd10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1dd20 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1dd30 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1dd40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1dd50 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1dd60 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1dd70 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1dd80 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
1dd90 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1dda0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1ddb0 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1ddc0 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1ddd0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1dde0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1ddf0 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1de00 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1de10 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20  QLITE_OK]).**   
1de20 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20         it first 
1de30 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20  sets *ppStmt to 
1de40 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1de50 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
1de60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1de70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1de80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1de90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1dea0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1deb0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1dec0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1ded0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1dee0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1def0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1df00 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1df10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1df20 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1df30 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1df40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1df50 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1df60 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1df70 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1df80 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1df90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1dfa0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1dfb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1dfc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1dfd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1dfe0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1dff0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e000 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1e010 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1e020 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1e030 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1e040 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1e050 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1e060 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1e070 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1e080 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e090 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1e0a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1e0b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1e0c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1e0d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1e0e0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1e0f0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1e100 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1e110 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e120 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1e130 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1e140 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1e150 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1e160 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1e170 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1e180 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1e190 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1e1a0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1e1b0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1e1c0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1e1d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1e1e0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1e1f0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1e200 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1e210 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1e220 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e230 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1e240 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1e250 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1e260 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1e270 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1e280 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1e290 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1e2a0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1e2b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1e2c0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1e2d0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1e2e0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1e2f0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1e300 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1e310 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1e320 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1e330 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1e340 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1e350 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1e360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a  ../*.** CAPIREF:
1e370 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1e380 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30  ement SQL {F1310
1e390 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
1e3a0 74 65 72 66 61 63 65 20 20 63 61 6e 20 62 65 20  terface  can be 
1e3b0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1e3c0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1e3d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1e3e0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1e3f0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1e400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1e410 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1e420 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31  S:.**.** {F13101
1e430 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1e440 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1e450 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1e460 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1e470 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1e480 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1e490 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1e4a0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1e4b0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1e4c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1e4e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e4f0 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  v2()],.**       
1e500 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
1e510 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e  _sql()] function
1e520 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1e530 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20  er to a.**      
1e540 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1e550 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  ted string conta
1e560 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65  ining a UTF-8 re
1e570 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ndering.**      
1e580 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69      of the origi
1e590 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  nal SQL statemen
1e5a0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32  t..**.** {F13102
1e5b0 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1e5c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1e5d0 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1e5e0 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1e5f0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1e600 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1e610 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1e620 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1e630 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1e640 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
1e650 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1e660 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
1e670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1e680 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1e690 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1e6a0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1e6b0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33  r..**.** {F13103
1e6c0 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1e6d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1e6e0 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1e6f0 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1e700 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1e710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1e720 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1e730 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e740 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1e750 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1e760 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1e770 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1e780 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d  CAPI3REF:  Dynam
1e790 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1e7a0 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30  ue Object  {F150
1e7b0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
1e7c0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1e7d0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1e7e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e7f0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1e800 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1e810 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e820 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1e830 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1e840 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1e850 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1e860 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ble..** SQLite u
1e870 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1e880 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ng for the value
1e890 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a  s it stores.  .*
1e8a0 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  * Values stored 
1e8b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1e8c0 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a   objects can be.
1e8d0 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  ** be integers, 
1e8e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1e8f0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1e900 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1e910 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1e920 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1e930 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1e940 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1e950 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1e960 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1e970 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1e980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1e990 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1e9a0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1e9b0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1e9c0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1e9d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e9e0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1e9f0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1ea00 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1ea10 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1ea20 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68  cifies .** wheth
1ea30 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1ea40 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1ea50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1ea60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1ea70 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1ea80 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1ea90 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1eaa0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1eab0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1eac0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1ead0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1eae0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1eaf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1eb00 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1eb10 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1eb20 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1eb30 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1eb40 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1eb50 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1eb60 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1eb70 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ith SQLITE_THREA
1eb80 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68  DSAFE=0 and with
1eb90 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1eba0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1ebb0 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  g 0).** then the
1ebc0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1ebd0 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
1ebe0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1ebf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ec00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1ec10 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a  and they can be.
1ec20 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  ** used intercha
1ec30 6e 67 65 61 62 6c 65 2e 20 20 48 6f 77 65 76 65  ngeable.  Howeve
1ec40 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  r, for maximum c
1ec50 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1ec60 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65  it.** is recomme
1ec70 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1ec80 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20  ations make the 
1ec90 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1eca0 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70  een.** between p
1ecb0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1ecc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ecd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1ece0 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61  ven if.** they a
1ecf0 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  re single thread
1ed00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1ed10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ed20 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1ed30 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1ed40 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1ed50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ed60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1ed70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 7c 20 61  ate_function | a
1ed80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1ed90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1eda0 5d 0a 2a 2a 20 61 72 65 20 70 72 6f 74 65 63 74  ].** are protect
1edb0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1edc0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1edd0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1ede0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1edf0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1ee00 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1ee10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1ee20 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1ee30 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1ee40 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1ee50 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1ee60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1ee70 5f 76 61 6c 75 65 28 29 5d 2e 20 20 0a 2a 2a 20  _value()].  .** 
1ee80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
1ee90 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
1eea0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
1eeb0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
1eec0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1eed0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1eee0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
1eef0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1ef00 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
1ef10 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
1ef20 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63  I3REF:  SQL Func
1ef30 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1ef40 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a  ect {F16001}.**.
1ef50 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
1ef60 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
1ef70 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
1ef80 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
1ef90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
1efa0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
1efb0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1efc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20  ite3_context.** 
1efd0 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73  object is always
1efe0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1eff0 20 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   to .** [sqlite3
1f000 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1f010 20 7c 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64   | application-d
1f020 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1f030 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1f040 70 6c 69 63 61 74 69 6f 6e 65 64 2d 64 65 66 69  plicationed-defi
1f050 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1f060 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1f070 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
1f080 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
1f090 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 0a  h into calls to.
1f0a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1f0b0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1f0c0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1f0d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1f0e0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 0a 2a 2a  e_context()],.**
1f0f0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1f100 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1f110 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1f120 61 6e 64 6c 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71  andle()],.** [sq
1f130 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
1f140 61 28 29 5d 2c 20 61 6e 64 2f 6f 72 20 5b 73 71  a()], and/or [sq
1f150 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1f160 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1f170 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1f180 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1f190 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1f1a0 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
1f1b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1f1c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1f1d0 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13500}.**.** 
1f1e0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1f1f0 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1f200 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f210 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61  )] and its.** va
1f220 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73  riants, literals
1f230 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20   may be replace 
1f240 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
1f250 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73  n one.** of thes
1f260 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1f270 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1f280 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1f290 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1f2a0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1f2b0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1f2c0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1f2d0 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1f2e0 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1f2f0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1f300 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61  al,.** VVV alpha
1f310 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1f320 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  er name..** The 
1f330 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20  values of these 
1f340 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1f350 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1f360 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a  rameter names".*
1f370 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  * or "SQL parame
1f380 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1f390 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1f3a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1f3b0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1f3c0 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
1f3d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1f3e0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1f3f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1f400 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20   always.** is a 
1f410 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1f420 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1f430 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1f440 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1f450 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1f460 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68  its variants. Th
1f470 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
1f480 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1f490 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  x of the paramet
1f4a0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68  er to be set. Th
1f4b0 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
1f4c0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1f4d0 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1f4e0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1f4f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
1f500 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
1f510 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
1f520 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
1f530 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
1f540 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
1f550 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1f560 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65  ce. .** The inde
1f570 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
1f580 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
1f590 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
1f5a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
1f5b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1f5c0 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  e()] API if desi
1f5d0 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
1f5e0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1f5f0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1f600 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1f610 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
1f620 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1f630 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
1f640 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
1f650 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
1f660 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
1f670 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1f680 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
1f690 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
1f6a0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
1f6b0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
1f6c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
1f6d0 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
1f6e0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1f6f0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1f700 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
1f710 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1f720 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1f730 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1f740 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1f750 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1f760 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68  tes</u>.** in th
1f770 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1f780 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1f790 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68  cters. .** If th
1f7a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1f7b0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1f7c0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1f7d0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
1f7e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1f7f0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
1f800 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1f810 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
1f820 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
1f830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f840 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
1f850 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
1f860 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1f870 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
1f880 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
1f890 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
1f8a0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
1f8b0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
1f8c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1f8d0 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
1f8e0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
1f8f0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
1f900 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
1f910 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
1f920 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
1f930 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
1f940 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
1f950 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
1f960 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1f970 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
1f980 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1f990 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
1f9a0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
1f9b0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
1f9c0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
1f9d0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
1f9e0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
1f9f0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
1fa00 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
1fa10 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
1fa20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
1fa30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1fa40 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
1fa50 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
1fa60 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
1fa70 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
1fa80 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72  th zeros.  A zer
1fa90 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1faa0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1fab0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1fac0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1fad0 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  it size) while i
1fae0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1faf0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1fb00 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1fb10 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1fb20 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1fb30 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1fb40 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1fb50 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  tten using .** [
1fb60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1fb70 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c  n | increment BL
1fb80 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1fb90 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20  . A negative.** 
1fba0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1fbb0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1fbc0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1fbd0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1fbe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1fbf0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1fc00 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1fc10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1fc20 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1fc30 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1fc40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1fc50 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1fc60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1fc70 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1fc80 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1fc90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1fca0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1fcb0 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1fcc0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1fcd0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1fce0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1fcf0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1fd00 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1fd10 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1fd20 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1fd30 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1fd40 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1fd50 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1fd60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1fd70 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1fd80 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1fd90 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1fda0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
1fdb0 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1fdc0 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1fdd0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1fde0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1fdf0 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1fe00 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1fe10 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1fe20 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1fe30 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1fe40 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1fe50 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1fe60 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1fe70 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1fe80 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1fe90 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1fea0 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1feb0 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1fec0 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1fed0 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1fee0 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1fef0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1ff00 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1ff10 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1ff20 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1ff30 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1ff40 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1ff50 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1ff60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1ff70 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1ff80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ff90 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1ffa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ffb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1ffc0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1ffd0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1ffe0 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13506} The [sqli
1fff0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51  te3_prepare | SQ
20000 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
20010 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
20020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b  .**          tok
20030 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  ens of the forms
20040 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
20050 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
20060 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20 20 20  d "@VVV".**     
20070 20 20 20 20 20 61 73 20 53 51 4c 20 70 61 72 61       as SQL para
20080 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20 4e 4e  meters, where NN
20090 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
200a0 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
200b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 67  .**          dig
200c0 69 74 73 20 61 6e 64 20 77 68 65 72 65 20 56 56  its and where VV
200d0 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
200e0 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
200f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c   .**          al
20100 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61 72 61  phanumeric chara
20110 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70  cters or "::" op
20120 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
20130 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
20140 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
20150 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73 20 61  ning no spaces a
20160 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  nd contained wit
20170 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e  hin parentheses.
20180 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20  .**.** {F13509} 
20190 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75  The initial valu
201a0 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  e of an SQL para
201b0 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  meter is NULL..*
201c0 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68  *.** {F13512} Th
201d0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
201e0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
201f0 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68  is one larger th
20200 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  an the.**       
20210 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78     largest index
20220 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
20230 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f  r to the left, o
20240 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  r 1 if.**       
20250 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68     the "?" is th
20260 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
20270 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
20280 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64  {F13515} The ind
20290 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20  ex of an "?NNN" 
202a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
202b0 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e   the integer NNN
202c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d  ..**.** {F13518}
202d0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
202e0 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c   ":VVV", "$VVV",
202f0 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70   or "@VVV" SQL p
20300 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
20310 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
20320 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   as the index of
20330 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72   leftmost occurr
20340 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d  ences of the sam
20350 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
20360 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20  rameter, or one 
20370 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61  more than the la
20380 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72  rgest index over
20390 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
203a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
203b0 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20  he left if this 
203c0 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  is the first occ
203d0 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20  urrence.**      
203e0 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61      of this para
203f0 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74  meter, or 1 if t
20400 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d  his is the leftm
20410 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ost parameter..*
20420 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54 68  *.** {F13521} Th
20430 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20440 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65  re | SQL stateme
20450 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69  nt compiler] fai
20460 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  l with.**       
20470 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41     an [SQLITE_RA
20480 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74 68  NGE] error if th
20490 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
204a0 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  L parameter.**  
204b0 20 20 20 20 20 20 20 20 69 73 20 6c 65 73 73 20          is less 
204c0 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74 65  than 1 or greate
204d0 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41  r than SQLITE_MA
204e0 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
204f0 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34  R..**.** {F13524
20500 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
20510 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
20520 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
20530 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,V,...)].**     
20540 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74       associate t
20550 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20  he value V with 
20560 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
20570 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20  rs having an.** 
20580 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f           index o
20590 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70  f N in the [prep
205a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
205b0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37  S..**.** {F13527
205c0 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
205d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
205e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
205f0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
20600 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f     override prio
20610 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65  r calls with the
20620 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20   same values of 
20630 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  S and N..**.** {
20640 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73  F13530} Bindings
20650 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20   established by 
20660 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
20670 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
20680 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  d(S,...)].**    
20690 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63        persist ac
206a0 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ross calls to [s
206b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
206c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d  ..**.** {F13533}
206d0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
206e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
206f0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
20700 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20710 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
20720 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
20730 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20740 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
20750 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
20760 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20  binds the first 
20770 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  L.**          by
20780 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20  tes of the blob 
20790 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  or string pointe
207a0 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20  d to by V, when 
207b0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  L.**          is
207c0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
207d0 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e  *.** {F13536} In
207e0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
207f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
20800 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20  ,V,L,D)] or.**  
20810 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20820 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
20830 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
20840 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73  binds characters
20850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
20860 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20  m V through the 
20870 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
20880 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e  cter when L is n
20890 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
208a0 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73  F13539} In calls
208b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
208c0 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
208d0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
208e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
208f0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
20900 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
20910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20920 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
20930 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
20940 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
20950 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
20960 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69  TE_STATIC], SQLi
20970 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
20980 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20  the value V.**  
20990 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20          is held 
209a0 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61  in static unmana
209b0 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77  ged space that w
209c0 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a  ill not change.*
209d0 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e  *          durin
209e0 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
209f0 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a  f the binding..*
20a00 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e  *.** {F13542} In
20a10 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20a20 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
20a30 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
20a40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
20a50 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
20a60 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
20a70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20a80 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20a90 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
20aa0 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20  the special.**  
20ab0 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74          constant
20ac0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
20ad0 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65  NT], the routine
20ae0 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20   makes a .**    
20af0 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f        private co
20b00 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62 65  py of V value be
20b10 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
20b20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20  .**.** {F13545} 
20b30 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
20b40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
20b50 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
20b60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20b70 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
20b80 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
20b90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20ba0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
20bb0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
20bc0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
20bd0 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e  *          a fun
20be0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e  ction, SQLite in
20bf0 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74  vokes that funct
20c00 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74  ion to destroy t
20c10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56  he.**          V
20c20 20 76 61 6c 75 65 20 61 66 74 65 72 20 69 74 20   value after it 
20c30 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
20c40 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a  ng the V value..
20c50 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49  **.** {F13548} I
20c60 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20c70 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
20c80 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20  b(S,N,V,L)] the 
20c90 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20  value bound.**  
20ca0 20 20 20 20 20 20 20 20 69 73 20 61 20 62 6c 6f          is a blo
20cb0 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72  b of L bytes, or
20cc0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62   a zero-length b
20cd0 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67 61  lob if L is nega
20ce0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20cf0 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  551} In calls to
20d00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
20d10 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65  alue(S,N,V)] the
20d20 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a   V argument may.
20d30 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65  **          be e
20d40 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74  ither a [protect
20d50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20d60 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a  ] object or an.*
20d70 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72  *          [unpr
20d80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20d90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
20da0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
20db0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
20dc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
20dd0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
20de0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
20df0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20e00 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
20e10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
20e20 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
20e30 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
20e40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
20e50 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20e60 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
20e70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20e80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20e90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20ea0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
20eb0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
20ec0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20ed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20ee0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
20ef0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
20f00 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20f10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20f20 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
20f30 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20f40 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
20f50 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
20f60 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20f70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20f80 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
20f90 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
20fa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
20fb0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
20fc0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
20fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20fe0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
20ff0 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36  Parameters {F136
21000 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00}.**.** This r
21010 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
21020 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
21030 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61 72  umber of SQL par
21040 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20  ameters.** in a 
21050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21060 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  nt.  SQL paramet
21070 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
21080 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
21090 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
210a0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
210b0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
210c0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
210d0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
210e0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
210f0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
21100 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
21110 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
21120 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
21130 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
21140 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
21150 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
21160 72 67 65 73 74 20 70 61 72 61 6d 65 74 65 72 2e  rgest parameter.
21170 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  .** For all form
21180 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
21190 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
211a0 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ond to the numbe
211b0 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70  r of.** unique p
211c0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
211d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
211e0 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 20   ?NNN are used, 
211f0 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20  there may.** be 
21200 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
21210 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21220 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21230 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21240 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21250 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21260 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
21270 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21280 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21290 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
212a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
212b0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
212c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
212d0 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
212e0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
212f0 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
21300 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
21310 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
21320 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
21330 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
21340 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
21350 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  if S.**         
21360 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
21370 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
21380 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21390 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
213a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
213b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
213c0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
213d0 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36   Parameter {F136
213e0 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  20}.**.** This r
213f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
21400 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
21410 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
21420 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
21430 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  r in a [prepared
21440 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
21450 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
21460 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
21470 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
21480 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
21490 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
214a0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
214b0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
214c0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
214d0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
214e0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
214f0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
21500 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
21510 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
21520 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
21530 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
21540 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
21550 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
21560 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
21570 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
21580 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a  ave no name..**.
21590 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73  ** The first hos
215a0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
215b0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
215c0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ot 0..**.** If t
215d0 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75  he value n is ou
215e0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
215f0 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65   the n-th parame
21600 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
21610 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
21620 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
21630 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
21640 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
21650 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
21660 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
21670 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
21680 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
21690 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
216a0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
216b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
216c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
216d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
216e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
216f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21700 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
21710 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
21720 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
21730 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
21740 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21750 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21760 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21770 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d  :.**.** {F13621}
21780 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
21790 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
217a0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
217b0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
217c0 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
217d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
217e0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
217f0 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
21800 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
21810 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
21820 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f  aving index N, o
21830 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55  r.**          NU
21840 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
21850 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  o SQL parameter 
21860 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20  with index N or 
21870 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
21880 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
21890 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20  h index N is an 
218a0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
218b0 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73  ter "?"..*/.cons
218c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
218d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
218e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
218f0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
21900 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
21910 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
21920 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
21930 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13640}.**.** 
21940 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
21950 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
21960 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
21970 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64  ame.  The.** ind
21980 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
21990 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
219a0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
219b0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
219c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
219d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
219e0 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a  ind()].  A zero.
219f0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
21a00 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
21a10 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
21a20 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72  .  The parameter
21a30 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
21a40 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
21a50 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
21a60 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
21a70 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
21a80 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
21a90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
21aa0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
21ab0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
21ac0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21ad0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
21ae0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
21af0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
21b00 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
21b10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21b20 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
21b30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21b40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34  TS:.**.** {F1364
21b50 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
21b60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21b70 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ndex(S,N)] inter
21b80 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
21b90 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64           the ind
21ba0 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
21bb0 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65 64  ter in [prepared
21bc0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
21bd0 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20          S whose 
21be0 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65  name matches the
21bf0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c   UTF-8 string N,
21c00 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69   or 0 if there i
21c10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  s.**          no
21c20 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73   match..*/.int s
21c30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21c40 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
21c50 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
21c60 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
21c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21c80 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
21c90 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
21ca0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36   Statement {F136
21cb0 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  60}.**.** Contra
21cc0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
21cd0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
21ce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
21cf0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
21d00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
21d10 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
21d20 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72  gs] on a .** [pr
21d30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21d40 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75  ].  Use this rou
21d50 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74  tine to.** reset
21d60 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
21d70 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
21d80 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21d90 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54  **.** {F13661} T
21da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
21db0 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
21dc0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
21dd0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
21de0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62 69  SQL parameter bi
21df0 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70 61  ndings in [prepa
21e00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
21e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
21e20 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  k to NULL..*/.in
21e30 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
21e40 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
21e50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
21e60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
21e70 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
21e80 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
21e90 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  710}.**.** Retur
21ea0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
21eb0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
21ec0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
21ed0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70  ed by the .** [p
21ee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21ef0 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
21f00 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66   returns 0.** if
21f10 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
21f20 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
21f30 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
21f40 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78  data (for .** ex
21f50 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29  ample an UPDATE)
21f60 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21f70 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31  TS:.**.** {F1371
21f80 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
21f90 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
21fa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
21fb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
21fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
21fd0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
21fe0 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64  lt set generated
21ff0 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
22000 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22010 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
22020 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67   if S does not g
22030 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20 20  enerate.**      
22040 20 20 20 20 61 20 72 65 73 75 6c 74 20 73 65 74      a result set
22050 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22060 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
22070 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22080 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22090 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
220a0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
220b0 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a  t {F13720}.**.**
220c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
220d0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
220e0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
220f0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
22100 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
22110 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
22120 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
22130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22140 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
22150 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
22160 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
22170 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20  terminated UTF8 
22180 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
22190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
221a0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
221b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
221c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
221d0 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
221e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
221f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72  er is the.** [pr
22200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22210 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  ] that implement
22220 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  s the SELECT sta
22230 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  tement..** The s
22240 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
22250 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75  is the column nu
22260 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d  mber.  The left-
22270 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a  most column is.*
22280 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  * number 0..**.*
22290 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
222a0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
222b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
222c0 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  her the .** [pre
222d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
222e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
222f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22300 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69  ze()].** or unti
22310 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
22320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22330 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
22340 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
22350 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
22360 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  column..**.** If
22370 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
22380 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
22390 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
223a0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
223b0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
223c0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
223d0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
223e0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
223f0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
22400 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22410 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
22420 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
22430 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
22440 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
22450 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
22460 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
22470 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
22480 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
22490 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
224a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
224b0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
224c0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
224d0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
224e0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
224f0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
22500 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
22510 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d  :.**.** {F13721}
22520 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
22530 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
22540 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22550 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  name(S,N)].**   
22560 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
22570 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
22580 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
22590 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
225a0 28 77 68 65 72 65 20 30 20 69 73 20 74 68 65 20  (where 0 is the 
225b0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
225c0 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ) for the.**    
225d0 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
225e0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
225f0 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a  atement] S as a.
22600 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
22610 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
22620 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
22630 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63 65  {F13723} A succe
22640 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
22650 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
22660 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
22670 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
22680 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22690 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
226a0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
226b0 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
226c0 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
226d0 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
226e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
226f0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
22700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22710 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
22720 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
22730 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72  nated UTF-16 str
22740 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ing in the nativ
22750 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
22760 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65  .** {F13724} The
22770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22780 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71  _name()] and [sq
22790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
227a0 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  e16()].**       
227b0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
227c0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
227d0 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20  ter if they are 
227e0 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20  unable to.**    
227f0 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d        allocate m
22800 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
22810 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72  eir normal retur
22820 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a  n strings..**.**
22830 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 65   {F13725} If the
22840 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
22850 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22860 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  name(S,N)] or.**
22870 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22880 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22890 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66  (S,N)] is out of
228a0 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65   range, then the
228b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
228c0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
228d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
228e0 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54  * .** {F13726} T
228f0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
22900 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
22910 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
22920 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
22930 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
22940 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
22950 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
22960 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
22970 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
22980 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
22990 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
229a0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
229b0 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
229c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
229d0 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
229e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d  ..**.** {F13727}
229f0 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
22a00 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
22a10 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
22a20 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
22a30 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
22a40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
22a50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
22a60 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20  identifier.**   
22a70 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69         to the ri
22a80 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65  ght of the AS ke
22a90 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  yword..*/.const 
22aa0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
22ab0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
22ac0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
22ad0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22af0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
22b00 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
22b10 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
22b20 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
22b30 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33  uery Result {F13
22b40 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  740}.**.** These
22b50 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
22b60 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
22b70 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75  ermine what colu
22b80 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61  mn of what.** ta
22b90 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74  ble in which dat
22ba0 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f  abase a result o
22bb0 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
22bc0 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
22bd0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
22be0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
22bf0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
22c00 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
22c10 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
22c20 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74 72  TF8 or UTF16 str
22c30 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
22c40 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
22c50 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
22c60 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
22c70 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
22c80 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
22c90 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
22ca0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
22cb0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
22cc0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
22cd0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
22ce0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
22cf0 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 61 72 65  .** the [prepare
22d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
22d10 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
22d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
22d30 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
22d40 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
22d50 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
22d60 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
22d70 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
22d80 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
22d90 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
22da0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
22db0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
22dc0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
22dd0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
22de0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
22df0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22e00 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
22e10 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65   calls is a [pre
22e20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22e30 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  ..** These funct
22e40 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
22e50 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
22e60 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
22e70 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65  urned by .** the
22e80 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
22e90 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
22ea0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
22eb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ent..**.** If th
22ec0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
22ed0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
22ee0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
22ef0 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75  ression.** or su
22f00 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
22f10 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
22f20 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
22f30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ese functions.**
22f40 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 54   return NULL.  T
22f50 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
22f60 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
22f70 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a  ULL if a memory.
22f80 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ** allocation er
22f90 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 4f 74 68  ror occurs.  Oth
22fa0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
22fb0 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65  urn the .** name
22fc0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
22fd0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
22fe0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74   and column that
22ff0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
23000 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
23010 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
23020 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
23030 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
23040 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
23050 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
23060 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
23070 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
23080 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
23090 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
230a0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
230b0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
230c0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
230d0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
230e0 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  iled with the .*
230f0 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  * SQLITE_ENABLE_
23100 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20  COLUMN_METADATA 
23110 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
23120 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
23130 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49  ** {U13751}.** I
23140 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
23150 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
23160 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
23170 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
23180 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
23190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
231a0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
231b0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
231c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
231d0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
231e0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
231f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20  .**.** {F13741} 
23200 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
23210 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
23220 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
23230 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
23240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
23250 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
23260 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
23270 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
23280 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
23290 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
232a0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
232b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
232c0 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
232d0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
232e0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
232f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
23300 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
23310 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
23320 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
23330 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
23340 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
23350 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
23360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
23370 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {F13742} The [s
23380 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23390 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
233a0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
233b0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
233c0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
233d0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
233e0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
233f0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
23400 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
23410 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
23420 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
23430 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
23440 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
23450 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
23460 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
23470 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
23480 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
23490 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a  umn of S is a.**
234a0 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61            genera
234b0 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
234c0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
234d0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
234e0 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
234f0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20  e the name..**  
23500 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33          .** {F13
23510 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  743} The [sqlite
23520 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
23530 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
23540 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
23550 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
23560 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
23570 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
23580 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20   the table from 
23590 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20  which the .**   
235a0 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
235b0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65  t column of [pre
235c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
235d0 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S .**          
235e0 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
235f0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
23600 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
23610 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
23620 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
23630 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
23640 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
23650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
23660 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
23670 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
23680 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {F13744} The [sq
23690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
236a0 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
236b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
236c0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
236d0 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
236e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
236f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
23700 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
23710 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
23720 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
23730 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
23740 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
23750 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23760 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
23770 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
23780 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
23790 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
237a0 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
237b0 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
237c0 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
237d0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
237e0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
237f0 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
23800 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
23810 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54 68   .** {F13745} Th
23820 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23830 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
23840 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
23850 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
23860 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
23870 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
23880 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
23890 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
238a0 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
238b0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
238c0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
238d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
238e0 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
238f0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
23900 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
23910 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
23920 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
23930 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
23940 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
23950 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
23960 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
23970 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
23980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
23990 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73   {F13746} The [s
239a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
239b0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  igin_name16(S,N)
239c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
239d0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
239e0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
239f0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
23a00 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
23a10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
23a20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
23a30 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
23a40 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
23a50 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
23a60 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
23a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23a80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
23a90 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
23aa0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
23ab0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
23ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
23ad0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
23ae0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
23af0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
23b00 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
23b10 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
23b20 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
23b30 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72  13748} The retur
23b40 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a  n values from.**
23b50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
23b60 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
23b70 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d  se_name|column m
23b80 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
23b90 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
23ba0 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20  are valid.**    
23bb0 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6c 69        for the li
23bc0 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70  fetime of the [p
23bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23be0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  t].**          o
23bf0 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f  r until the enco
23c00 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20  ding is changed 
23c10 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64  by another metad
23c20 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
23c30 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66  interface call f
23c40 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70  or the same prep
23c50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
23c60 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
23c70 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
23c80 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49 66 20  .** {U13751} If 
23c90 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
23ca0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
23cb0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
23cc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23cd0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63  _database_name|c
23ce0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
23cf0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
23d00 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
23d10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23d20 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
23d30 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
23d40 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74     at the same t
23d50 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
23d60 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
23d70 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
23d80 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
23d90 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
23da0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23db0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
23dc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23dd0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
23de0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
23df0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
23e00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
23e10 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
23e20 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
23e30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23e40 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
23e50 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
23e60 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
23e70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
23e80 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
23e90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23ea0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
23eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
23ec0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
23ed0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23ee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23ef0 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
23f00 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
23f10 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a  esult {F13760}.*
23f20 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
23f30 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
23f40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23f50 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20  t]. .** If this 
23f60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53  statement is a S
23f70 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
23f80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
23f90 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65  mn of the .** re
23fa0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
23fb0 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54  t of that SELECT
23fc0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
23fd0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
23fe0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
23ff0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
24000 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
24010 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
24020 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
24030 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
24040 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
24050 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
24060 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
24070 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
24080 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
24090 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
240a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
240b0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
240c0 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a  ncoded.  {END} .
240d0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
240e0 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
240f0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
24100 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
24110 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
24120 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   And the followi
24130 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  ng statement com
24140 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
24150 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
24160 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68  ROM t1;.**.** Th
24170 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
24180 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
24190 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
241a0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
241b0 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  .** result colum
241c0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
241d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
241e0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
241f0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d  t column.** (i==
24200 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
24210 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
24220 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
24230 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
24240 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
24250 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
24260 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
24270 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
24280 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
24290 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
242a0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
242b0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
242c0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
242d0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
242e0 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
242f0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
24300 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
24310 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
24320 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
24330 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
24340 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
24350 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
24360 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
24370 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24380 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20 41 20  .** {F13761}  A 
24390 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
243a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
243b0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
243c0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
243d0 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
243e0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
243f0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
24400 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24410 20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64    the declared d
24420 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
24430 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
24440 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
24450 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
24460 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
24470 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
24480 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
24490 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
244a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
244b0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
244c0 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
244d0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
244e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
244f0 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
24500 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
24510 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
24520 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
24530 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
24540 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
24550 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
24560 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
24570 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
24580 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
24590 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
245a0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
245b0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
245c0 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
245d0 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
245e0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
245f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24600 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33  S..**.** {F13763
24610 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
24620 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
24630 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
24640 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
24650 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
24660 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70  of columns in [p
24670 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24680 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  t] S.**         
24690 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20    or if the Nth 
246a0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
246b0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  n expression or 
246c0 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a  subquery rather.
246d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
246e0 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  n a table column
246f0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
24700 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
24710 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
24720 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
24730 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
24740 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
24750 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
24760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24770 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
24780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
24790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
247a0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
247b0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
247c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
247d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
247e0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
247f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
24800 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24810 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
24820 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
24830 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45  ../* .** CAPI3RE
24840 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20  F:  Evaluate An 
24850 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
24860 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74  13200}.**.** Aft
24870 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65 64 20  er an [prepared 
24880 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
24890 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74  een prepared wit
248a0 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65  h a call.** to e
248b0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
248c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
248d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
248e0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f  16_v2()] or to o
248f0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67  ne of.** the leg
24900 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
24910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
24920 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
24930 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
24940 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69  then this functi
24950 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  on must be calle
24960 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
24970 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
24980 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  the .** statemen
24990 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
249a0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
249b0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c  vior of this sql
249c0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
249d0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
249e0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
249f0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
24a00 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
24a10 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
24a20 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
24a30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
24a40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
24a50 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
24a60 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
24a70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
24a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
24a90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
24aa0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
24ab0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
24ac0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
24ad0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
24ae0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
24af0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
24b00 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
24b10 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
24b20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
24b30 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
24b40 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
24b50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
24b60 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
24b70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a  [SQLITE_BUSY], .
24b80 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
24b90 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
24ba0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
24bb0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
24bc0 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  E]..** With the 
24bd0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
24be0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
24bf0 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
24c00 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72  sult code].** or
24c10 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
24c20 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
24c30 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68  esult code] migh
24c40 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
24c50 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  .** well..**.** 
24c60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
24c70 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
24c80 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
24c90 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
24ca0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
24cb0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
24cc0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
24cd0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
24ce0 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a  nt is a COMMIT.*
24cf0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
24d00 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
24d10 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
24d20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
24d30 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
24d40 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
24d50 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
24d60 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72  COMMIT and occur
24d70 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
24d80 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
24d90 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
24da0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
24db0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
24dc0 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
24dd0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
24de0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
24df0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
24e00 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
24e10 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
24e20 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
24e30 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
24e40 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
24e50 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
24e60 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
24e70 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
24e80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
24e90 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
24ea0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
24eb0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
24ec0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
24ed0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
24ee0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
24ef0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
24f00 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
24f10 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57   .** [SQLITE_ROW
24f20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  ] is returned ea
24f30 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
24f40 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
24f50 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73  dy.** for proces
24f60 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c  sing by the call
24f70 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
24f80 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
24f90 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
24fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
24fb0 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20  | column access 
24fc0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
24fd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
24fe0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
24ff0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
25000 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
25010 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ** .** [SQLITE_E
25020 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
25030 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
25040 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
25050 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
25060 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
25070 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
25080 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
25090 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
250a0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
250b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
250c0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
250d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
250e0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
250f0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
25100 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
25110 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
25120 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20  de (example:.** 
25130 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
25140 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
25150 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
25160 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
25170 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
25180 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
25190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
251a0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
251b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
251c0 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
251d0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
251e0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
251f0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
25200 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
25210 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
25220 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
25230 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
25240 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
25250 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
25260 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
25270 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
25280 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
25290 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
252a0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
252b0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
252c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
252d0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
252e0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
252f0 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20   .** previously 
25300 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
25310 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
25320 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
25330 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
25340 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
25350 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
25360 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
25370 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
25380 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
25390 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
253a0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
253b0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
253c0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a  face Alert:</b>.
253d0 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
253e0 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20   interface, .** 
253f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
25400 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  () API always re
25410 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
25420 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b  error code,.** [
25430 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
25440 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72  ollowing any err
25450 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
25460 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61  QLITE_BUSY].** a
25470 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
25480 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
25490 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ll [sqlite3_rese
254a0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
254b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
254c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
254d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63   one of the spec
254e0 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  ific.** [error c
254f0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
25500 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
25510 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
25520 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
25530 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
25540 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
25550 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
25560 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
25570 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
25580 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
25590 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
255a0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
255b0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
255c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
255d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
255e0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
255f0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
25600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25610 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25620 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
25630 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20  en the .** more 
25640 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
25650 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
25660 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
25670 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
25680 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
25690 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
256a0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
256b0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
256c0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30  TS:.**.** {F1320
256d0 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72 65 64  2}  If [prepared
256e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
256f0 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20   ready to be.** 
25700 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c 20 74            run, t
25710 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hen [sqlite3_ste
25720 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74  p(S)] advances t
25730 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61  hat prepared sta
25740 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  tement.**       
25750 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d      until to com
25760 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c  pletion or until
25770 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20   it is ready to 
25780 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a  return another.*
25790 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  *           row 
257a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
257b0 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70  t or an interrup
257c0 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72  t or run-time er
257d0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
257e0 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65 6e  * {F15304}  When
257f0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
25800 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75  te3_step(S)] cau
25810 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ses the .**     
25820 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25830 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
25840 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
25850 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n,.**           
25860 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
25870 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  urns [SQLITE_DON
25880 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30  E]..**.** {F1530
25890 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  6}  When a call 
258a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
258b0 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75  (S)] stops becau
258c0 73 65 20 69 74 20 69 73 20 72 65 61 64 79 0a 2a  se it is ready.*
258d0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 72  *           to r
258e0 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
258f0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
25900 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 0a  set, it returns.
25910 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
25920 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ROW]..**.**
25930 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61 20   {F15308}  If a 
25940 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25950 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e  _step(S)] encoun
25960 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ters an.**      
25970 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e       [sqlite3_in
25980 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75 70  terrupt|interrup
25990 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65  t] or a run-time
259a0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
259b0 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20       it returns 
259c0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
259d0 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69  rror code that i
259e0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20  s not one of.** 
259f0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
25a00 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  E_OK], [SQLITE_R
25a10 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OW], or [SQLITE_
25a20 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  DONE]..**.** {F1
25a30 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71  5310}  If an [sq
25a40 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 7c  lite3_interrupt|
25a50 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 72 75  interrupt] or ru
25a60 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20  n-time error.** 
25a70 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73            occurs
25a80 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74   during a call t
25a90 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
25aa0 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
25ab0 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64   for a [prepared
25ac0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72   statement] S cr
25ad0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
25ae0 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20           legacy 
25af0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
25b00 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
25b10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
25b20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25b30 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75  6()] then the fu
25b40 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65  nction returns e
25b50 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25b60 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
25b70 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
25b80 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
25b90 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  USE]..*/.int sql
25ba0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
25bb0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
25bc0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
25bd0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25be0 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46 31  a result set {F1
25bf0 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3770}.**.** Retu
25c00 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
25c10 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63   values in the c
25c20 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
25c30 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a  e result set..**
25c40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
25c50 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20  **.** {F13771}  
25c60 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20  After a call to 
25c70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25c80 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 0a 2a  ] that returns.*
25c90 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
25ca0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73  ITE_ROW], the [s
25cb0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
25cc0 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a  t(S)] routine.**
25cd0 20 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20             will 
25ce0 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
25cf0 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a 20  value as the.** 
25d00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
25d10 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
25d20 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  S)] function..**
25d30 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41 66  .** {F13772}  Af
25d40 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
25d50 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e  p(S)] has return
25d60 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ed any value oth
25d70 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
25d80 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
25d90 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c  ] or before [sql
25da0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
25db0 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20  s been .**      
25dc0 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74       called on t
25dd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25de0 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20  tement] for.**  
25df0 20 20 20 20 20 20 20 20 20 74 68 65 20 66 69 72           the fir
25e00 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74  st time since it
25e10 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72   was [sqlite3_pr
25e20 65 70 61 72 65 7c 70 72 65 70 61 72 65 64 5d 0a  epare|prepared].
25e30 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
25e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 7c 72  [sqlite3_reset|r
25e50 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69  eset], the [sqli
25e60 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
25e70 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
25e80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
25e90 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
25ea0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25ec0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25ed0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
25ee0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46 31  al Datatypes {F1
25ef0 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0265}.** KEYWORD
25f00 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
25f10 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76 65  *.** {F10266}Eve
25f20 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
25f30 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
25f40 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
25f50 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
25f60 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
25f70 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
25f80 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
25f90 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
25fa0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
25fb0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
25fc0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
25fd0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b   NULL.** </ul> {
25fe0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
25ff0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
26000 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
26010 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
26020 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
26030 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
26040 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
26050 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
26060 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
26070 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
26080 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
26090 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
260a0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
260b0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
260c0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
260d0 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
260e0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
260f0 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  XT not.** SQLITE
26100 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
26110 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
26120 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
26130 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
26140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
26150 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
26160 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
26170 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
26180 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
26190 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
261a0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
261b0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
261c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
261d0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
261e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
261f0 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d  ults Values From
26200 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30 30   A Query {F13800
26210 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
26220 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
26230 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72  "result set quer
26240 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  y" interface..**
26250 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
26260 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
26270 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61  ation about.** a
26280 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
26290 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  f the current re
262a0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
262b0 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a  ery.  In every.*
262c0 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  * case the first
262d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
262e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ointer to the .*
262f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26300 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
26310 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65  eing.** evaluate
26320 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
26330 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20  stmt*] that was 
26340 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a  returned from .*
26350 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
26360 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
26370 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
26380 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f   and.** the seco
26390 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
263a0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
263b0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
263c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a   information .**
263d0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
263e0 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ned.  The left-m
263f0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
26400 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  e result set.** 
26410 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
26420 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
26430 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
26440 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
26450 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
26460 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
26470 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64  * the column ind
26480 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
26490 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
264a0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a  s undefined. .**
264b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
264c0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
264d0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
264e0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
264f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
26500 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
26510 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
26520 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
26530 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
26540 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
26550 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e  lize()] has been
26560 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74   call subsequent
26570 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
26580 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
26590 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
265a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
265b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
265c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
265d0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
265e0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
265f0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
26600 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
26610 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
26620 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26630 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
26640 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
26650 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26660 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
26670 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
26680 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
26690 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
266a0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
266b0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
266c0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
266d0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
266e0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a   undefined.  .**
266f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26700 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
26710 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a  utine returns .*
26720 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
26730 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
26740 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
26750 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
26760 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
26770 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
26780 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
26790 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
267a0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
267b0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
267c0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
267d0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
267e0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
267f0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
26800 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
26810 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
26820 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
26830 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
26840 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
26850 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
26860 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
26870 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
26880 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
26890 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
268a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
268b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
268c0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
268d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
268e0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
268f0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
26900 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
26910 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
26920 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
26930 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
26940 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
26950 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
26960 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
26970 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20  umn_bytes() .** 
26980 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
26990 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
269a0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
269b0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
269c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
269d0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
269e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
269f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
26a00 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
26a10 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
26a20 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
26a30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
26a40 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
26a50 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
26a60 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
26a70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26a80 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
26a90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
26aa0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
26ab0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
26ac0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
26ad0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
26ae0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
26af0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
26b00 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
26b10 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
26b20 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
26b30 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
26b40 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
26b50 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
26b60 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
26b70 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
26b80 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
26b90 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
26ba0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
26bb0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
26bc0 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
26bd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
26be0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
26bf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26c00 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
26c10 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
26c20 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
26c30 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
26c40 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
26c50 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
26c60 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
26c70 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f   zero-length blo
26c80 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  b is an arbitrar
26c90 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
26ca0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
26cb0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
26cc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
26cd0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
26ce0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
26cf0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
26d00 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
26d10 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
26d20 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
26d30 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
26d40 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
26d50 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a  TF-8.  .** The z
26d60 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
26d70 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
26d80 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
26d90 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
26da0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
26db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
26dc0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
26dd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26de0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
26df0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
26e00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26e10 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
26e20 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
26e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
26e40 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
26e50 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
26e60 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
26e70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26e80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26e90 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
26ea0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26eb0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
26ec0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
26ed0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
26ee0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
26ef0 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69  s like .** [sqli
26f00 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
26f10 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26f20 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71  _text()], or [sq
26f30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
26f40 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  s()],.** then th
26f50 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
26f60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
26f70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
26f80 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
26f90 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
26fa0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
26fb0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
26fc0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
26fd0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
26fe0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
26ff0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
27000 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
27010 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
27020 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
27030 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76  y to do the conv
27040 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61  ersion.** automa
27050 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
27060 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
27070 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
27080 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72  sions that.** ar
27090 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
270a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
270b0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
270c0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
270d0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
270e0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
270f0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
27100 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
27110 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
27120 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
27130 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
27140 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
27150 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
27160 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
27170 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
27180 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
27190 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
271a0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
271b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
271c0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
271d0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
271e0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
271f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
27200 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
27210 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
27220 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
27230 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
27240 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
27250 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
27260 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
27270 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
27280 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
27290 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
272a0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
272b0 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45  Same as for INTE
272c0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
272d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
272e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
272f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
27300 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
27310 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
27320 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
27330 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
27340 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
27350 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
27360 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
27370 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
27380 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
27390 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
273a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
273b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
273c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
273d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
273e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
273f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
27400 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
27410 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
27420 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
27430 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
27440 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
27450 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
27460 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
27470 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
27480 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
27490 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
274a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
274b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
274c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
274d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
274e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
274f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
27500 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
27510 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
27520 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
27530 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
27540 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
27550 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
27560 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
27570 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
27580 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
27590 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
275a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
275b0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
275c0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
275d0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
275e0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
275f0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
27600 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
27610 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
27620 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
27630 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
27640 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
27650 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
27660 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
27670 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
27680 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
27690 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
276a0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
276b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
276c0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
276d0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
276e0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
276f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
27700 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
27710 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  d. .** Type conv
27720 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
27730 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
27740 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
27750 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
27760 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
27770 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  ul>.** <li><p>  
27780 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
27790 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
277a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
277b0 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20  _text() .**     
277c0 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f       or sqlite3_
277d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
277e0 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
277f0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
27800 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ght.**          
27810 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
27820 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
27830 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
27840 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
27850 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
27860 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
27870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27880 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
27890 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
278a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
278b0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
278c0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
278d0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
278e0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
278f0 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  p></li>.**.** <l
27900 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
27910 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
27920 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
27930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27940 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
27950 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
27960 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
27970 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
27980 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
27990 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
279a0 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c  to UTF-8.</p></l
279b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
279c0 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65  * Conversions be
279d0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
279e0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
279f0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
27a00 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
27a10 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
27a20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
27a30 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
27a40 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27a50 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
27a60 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
27a70 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
27a80 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
27a90 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
27aa0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
27ab0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
27ac0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
27ad0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
27ae0 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a  sometime it is.*
27af0 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  * not possible a
27b00 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
27b10 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
27b20 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
27b30 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  .  .**.** The sa
27b40 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
27b50 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
27b60 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
27b70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
27b80 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
27b90 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
27ba0 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20  .**.**  <ul>.** 
27bb0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
27bc0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
27bd0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
27be0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
27bf0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
27c00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
27c10 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
27c20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27c30 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
27c40 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
27c50 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
27c60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
27c70 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
27c80 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a  i>.**  </ul>.**.
27c90 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
27ca0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
27cb0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
27cc0 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  n_text(), sqlite
27cd0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
27ce0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
27cf0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
27d00 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
27d10 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68  e result into th
27d20 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72  e desired.** for
27d30 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
27d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27d50 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74  bytes() or sqlit
27d60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27d70 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74  6() to.** find t
27d80 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
27d90 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
27da0 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ix call to sqlit
27db0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
27dc0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
27dd0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
27de0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
27df0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27e00 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74  6().  And do not
27e10 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  .** mix calls to
27e20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27e30 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61  text16() with ca
27e40 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
27e50 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
27e60 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
27e70 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
27e80 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
27e90 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
27ea0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
27eb0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
27ec0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
27ed0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
27ee0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
27ef0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27f00 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
27f10 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63   The memory spac
27f20 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
27f30 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c  trings.** and bl
27f40 6f 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74  obs is freed aut
27f50 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
27f60 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
27f70 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
27f80 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
27f90 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
27fa0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
27fb0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
27fc0 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  into .** [sqlite
27fd0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
27fe0 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
27ff0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
28000 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
28010 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
28020 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
28030 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
28040 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
28050 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
28060 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
28070 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
28080 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
28090 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
280a0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
280b0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
280c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
280d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
280e0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
280f0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
28100 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
28110 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33  S:.**.** {F13803
28120 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
28130 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
28140 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28150 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
28160 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
28170 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
28180 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
28190 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
281a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
281b0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
281c0 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20  a blob and then 
281d0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
281e0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
281f0 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76   the converted v
28200 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  alue..**.** {F13
28210 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  806} The [sqlite
28220 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53  3_column_bytes(S
28230 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
28240 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
28250 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
28260 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c   bytes in the bl
28270 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  ob or string (ex
28280 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
28290 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
282a0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
282b0 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
282c0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
282d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
282e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
282f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
28300 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72  mn_blob(S,N)] or
28310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
28320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28330 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  t(S,N)]..**.** {
28340 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c  F13809} The [sql
28350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28360 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  s16(S,N)] interf
28370 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
28380 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
28390 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
283a0 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
283b0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
283c0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
283d0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
283e0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
283f0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
28400 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
28410 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
28420 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28430 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a  text16(S,N)]..**
28440 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65  .** {F13812} The
28450 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28460 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e  _double(S,N)] in
28470 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28480 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28490 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
284a0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
284b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
284c0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
284d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
284e0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
284f0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
28500 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
28510 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
28520 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
28530 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d  ..**.** {F13815}
28540 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
28550 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
28560 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
28570 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28580 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
28590 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
285a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
285b0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
285c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
285d0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
285e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
285f0 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
28600 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
28610 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
28620 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
28630 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20  .**.** {F13818} 
28640 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28650 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
28660 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28670 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28680 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
28690 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
286a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
286b0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
286c0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
286d0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
286e0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
286f0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
28700 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
28710 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
28720 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
28730 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3821} The [sqlit
28740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
28750 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
28760 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28770 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
28780 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
28790 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
287a0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
287b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
287c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
287d0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
287e0 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20  nated UTF-8 .** 
287f0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
28800 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
28810 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
28820 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
28830 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
28840 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28850 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
28860 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28870 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
28880 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
28890 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
288a0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
288b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
288c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
288d0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
288e0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
288f0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
28900 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
28910 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
28920 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
28930 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28940 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
28950 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  ng..**.** {F1382
28960 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
28970 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
28980 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
28990 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
289a0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
289b0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
289c0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
289d0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
289e0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
289f0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
28a00 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
28a10 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
28a20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
28a30 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
28a40 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
28a50 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
28a60 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
28a70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
28a80 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68  *.** {F13830} Th
28a90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28aa0 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e  n_value(S,N)] in
28ab0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28ac0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
28ad0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70  inter to an [unp
28ae0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28af0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
28b00 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
28b10 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
28b20 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
28b30 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28b40 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
28b50 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
28b60 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f  tement] S..*/.co
28b70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28b80 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
28b90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28ba0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
28bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28bd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
28be0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28bf0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
28c00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
28c10 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
28c20 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
28c30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
28c40 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
28c50 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
28c60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28c70 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
28c80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
28c90 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
28ca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28cb0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
28cc0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
28cd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
28ce0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28cf0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
28d00 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28d10 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
28d20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
28d30 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
28d40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
28d50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
28d60 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
28d70 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
28d80 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
28d90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
28da0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
28db0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
28dc0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28dd0 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30  t Object {F13300
28de0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
28df0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
28e00 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
28e10 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a  d to delete a .*
28e20 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
28e30 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73  ement]. If the s
28e40 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
28e50 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
28e60 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78  fully, or not ex
28e70 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
28e80 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  hen SQLITE_OK is
28e90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
28ea0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
28eb0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
28ec0 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b  ed then an .** [
28ed0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
28ee0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
28ef0 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
28f00 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ned. .**.** This
28f10 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
28f20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
28f30 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
28f40 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
28f50 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
28f60 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
28f70 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
28f80 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d   has not .** com
28f90 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
28fa0 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
28fb0 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
28fc0 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
28fd0 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
28fe0 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  ror or an interr
28ff0 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69  upt.  (See [sqli
29000 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
29010 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  .) .** Incomplet
29020 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
29030 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
29040 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
29050 6e 63 65 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70  nceled,  .** dep
29060 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
29070 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
29080 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20   the .** [error 
29090 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
290a0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
290b0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  BORT]..**.** INV
290c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
290d0 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c  F11302} The [sql
290e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
290f0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
29100 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  roys the.**     
29110 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
29120 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20  tatement] S and 
29130 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20  releases all.** 
29140 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
29150 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63  and file resourc
29160 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20  es held by that 
29170 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  object..**.** {F
29180 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f  11304} If the mo
29190 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
291a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
291b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
291c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
291d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
291e0 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72  eturned an error
291f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
29200 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
29210 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73  lize(S)] returns
29220 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72   that same error
29230 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29240 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
29250 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29270 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
29280 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
29290 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a  ct {F13330}.**.*
292a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
292b0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
292c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
292d0 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  t a .** [prepare
292e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
292f0 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  ect..** back to 
29300 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
29310 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
29320 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41  e-executed..** A
29330 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
29340 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
29350 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
29360 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
29370 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
29380 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
29390 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
293a0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
293b0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
293c0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
293d0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
293e0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
293f0 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68  *.** {F11332} Th
29400 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
29410 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
29420 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
29430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
29450 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
29460 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
29470 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34  m..**.** {F11334
29480 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
29490 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
294a0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
294b0 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or .**          
294c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
294d0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
294e0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
294f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
29500 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
29510 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29520 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
29530 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
29540 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
29550 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
29560 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
29570 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
29580 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66  *.** {F11336} If
29590 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
295a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
295b0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a  3_step(S)] for.*
295c0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
295d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
295e0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
295f0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
29600 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
29610 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
29620 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29630 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
29640 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68  *.** {F11338} Th
29650 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
29660 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
29670 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
29680 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
29690 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
296a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
296b0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72  bindings] on [pr
296c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
296d0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
296e0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
296f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29710 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
29720 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
29730 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45  s {F16100}.** KE
29740 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
29750 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
29760 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73  nes} .**.** Thes
29770 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
29780 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
29790 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74  own as.** "funct
297a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
297b0 74 69 6e 65 73 22 29 20 61 72 65 20 75 73 65 64  tines") are used
297c0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
297d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
297e0 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64  tes.** or to red
297f0 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
29800 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  or of existing S
29810 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
29820 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
29830 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f  .** difference o
29840 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20  nly between the 
29850 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
29860 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29870 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  , the.** name of
29880 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
29890 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
298a0 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
298b0 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  in UTF-8 for.** 
298c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
298d0 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
298e0 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33  F-16 for sqlite3
298f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29900 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
29910 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29920 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
29930 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
29940 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
29950 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
29960 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
29970 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61  single.** progra
29980 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
29990 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65 20 63   one [database c
299a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72  onnection] inter
299b0 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a  nally, then SQL.
299c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  ** functions mus
299d0 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
299e0 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20  idually to each 
299f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29a00 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tion]..**.** The
29a10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
29a20 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
29a30 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
29a40 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a  n to be created.
29a50 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e  ** or redefined.
29a60 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  .** The length o
29a70 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
29a80 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
29a90 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
29aa0 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65   the .** zero-te
29ab0 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
29ac0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
29ad0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
29ae0 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
29af0 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20  haracters.  Any 
29b00 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
29b10 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
29b20 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
29b30 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
29b40 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  n an SQLITE_ERRO
29b50 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  R error..**.** T
29b60 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
29b70 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
29b80 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
29b90 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
29ba0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
29bb0 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68  ate takes. If th
29bc0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
29bd0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
29be0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
29bf0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
29c00 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
29c10 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
29c20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
29c30 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
29c40 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
29c50 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49  s what .** [SQLI
29c60 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
29c70 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
29c80 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
29c90 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
29ca0 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
29cb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
29cc0 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
29cd0 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
29ce0 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
29cf0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
29d00 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
29d10 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
29d20 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
29d30 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
29d40 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
29d50 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
29d60 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74   It is allowed t
29d70 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
29d80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29d90 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
29da0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29db0 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
29dc0 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
29dd0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
29de0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
29df0 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
29e00 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c  Rep..** When mul
29e10 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
29e20 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
29e30 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
29e40 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
29e50 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
29e60 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
29e70 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
29e80 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
29e90 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
29ea0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
29eb0 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
29ec0 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
29ed0 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a  not care what.**
29ee0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
29ef0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
29f00 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
29f10 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53   should be.** [S
29f20 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
29f30 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
29f40 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
29f50 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
29f60 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
29f70 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e  on.** of the fun
29f80 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
29f90 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
29fa0 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b  inter using.** [
29fb0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
29fc0 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  a()]..**.** The 
29fd0 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
29fe0 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
29ff0 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
2a000 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
2a010 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
2a020 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
2a030 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
2a040 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a  ement the SQL.**
2a050 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2a060 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72  regate. A scalar
2a070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2a080 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2a090 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  entation of.** t
2a0a0 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63  he xFunc callbac
2a0b0 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69  k only, NULL poi
2a0c0 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
2a0d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2a0e0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2a0f0 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e  l parameters. An
2a100 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2a110 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2a120 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2a130 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61  on.** of xStep a
2a140 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
2a150 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
2a160 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54  sed for xFunc. T
2a170 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65  o delete an.** e
2a180 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2a190 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2a1a0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
2a1b0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
2a1c0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
2a1d0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
2a1e0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
2a1f0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
2a200 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2a210 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
2a220 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
2a230 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
2a240 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
2a250 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
2a260 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
2a270 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
2a280 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
2a290 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
2a2a0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2a2b0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
2a2c0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2a2d0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2a2e0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2a2f0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
2a300 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2a310 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65  .** {F16103} The
2a320 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a330 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69  _function16()] i
2a340 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73  nterface behaves
2a350 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
2a360 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74       like [sqlit
2a370 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a380 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77  on()] in every w
2a390 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
2a3a0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
2a3b0 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75  terprets the zFu
2a3c0 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d  nctionName argum
2a3d0 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20  ent as.**       
2a3e0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
2a3f0 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
2a400 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
2a410 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20  ead of as a.**  
2a420 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
2a430 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a  minated UTF-8..*
2a440 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20  *.** {F16106} A 
2a450 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
2a460 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20  ation of.**     
2a470 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
2a480 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a490 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20  n(D,X,N,E,...)] 
2a4a0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2a4b0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
2a4c0 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c  or replaces call
2a4d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69  back functions i
2a4e0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
2a4f0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
2a500 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d        used to im
2a510 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2a520 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58  function named X
2a530 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65   with N paramete
2a540 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rs.**          a
2a550 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 66  nd having a pref
2a560 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2a570 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20  ing of E..**.** 
2a580 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63 63 65  {F16109} A succe
2a590 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
2a5a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a5b0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2a5c0 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
2a5d0 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74 68       replaces th
2a5e0 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c  e P, F, S, and L
2a5f0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79   values from any
2a600 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
2a610 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
2a620 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20  e same D, X, N, 
2a630 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a  and E values..**
2a640 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65  .** {F16112} The
2a650 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a660 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e  _function(D,X,..
2a670 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
2a680 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ils with.**     
2a690 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f       a return co
2a6a0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52  de of [SQLITE_ER
2a6b0 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20  ROR] if the SQL 
2a6c0 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20  function name X 
2a6d0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  is.**          l
2a6e0 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62  onger than 255 b
2a6f0 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f  ytes exclusive o
2a700 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  f the zero termi
2a710 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
2a720 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d  6118} Either F m
2a730 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20  ust be NULL and 
2a740 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
2a750 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a  NULL or else F.*
2a760 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
2a770 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  n-NULL and S and
2a780 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68   L are NULL, oth
2a790 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20  erwise.**       
2a7a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2a7b0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2a7c0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65  N,E,P,F,S,L)] re
2a7d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
2a7e0 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ROR]..**.** {F16
2a7f0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2a800 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a810 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
2a820 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
2a830 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
2a840 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
2a850 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65  ITE_BUSY] if the
2a860 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72  re exist [prepar
2a870 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2a880 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63  *          assoc
2a890 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
2a8a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a8b0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
2a8c0 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16124} The [sqli
2a8d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a8e0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20  ion(D,X,N,...)] 
2a8f0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
2a900 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2a910 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2a920 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
2a930 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
2a940 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20  (specifying the 
2a950 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
2a960 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20     of arguments 
2a970 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2a980 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74  ion being regist
2a990 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a  ered) is less.**
2a9a0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
2a9b0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2a9c0 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  n 127..**.** {F1
2a9d0 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
2a9e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2a9f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2aa00 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2aa10 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2aa20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
2aa30 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
2aa40 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2aa50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2aa60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
2aa70 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75  ed X when the nu
2aa80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2aa90 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2aaa0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ction is.**     
2aab0 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a       exactly N..
2aac0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57  **.** {F16130} W
2aad0 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65  hen N is -1, the
2aae0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2aaf0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ab00 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2ab10 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73    interface caus
2ab20 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  es callbacks to 
2ab30 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
2ab40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
2ab50 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
2ab60 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d  d X with any num
2ab70 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2ab80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d  ..**.** {F16133}
2ab90 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
2aba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2abb0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2abc0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2abd0 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
2abe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2abf0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2ac00 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20  ction X.**      
2ac10 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65      and when one
2ac20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ac30 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65  has N>=0 and the
2ac40 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31   other has N=(-1
2ac50 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ).**          th
2ac60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ac70 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
2ac80 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64 2e   N is preferred.
2ac90 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20  .**.** {F16136} 
2aca0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
2acb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2acc0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2acd0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2ace0 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2acf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ad00 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2ad10 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a  nction X with.**
2ad20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2ad30 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  me number of arg
2ad40 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74  uments N but wit
2ad50 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20  h different.**  
2ad60 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67          encoding
2ad70 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d  s E, then the im
2ad80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
2ad90 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65  re E matches the
2ada0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
2adb0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2adc0 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  s preferred..**.
2add0 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20  ** {F16139} For 
2ade0 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  an aggregate SQL
2adf0 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65   function create
2ae00 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
2ae10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
2ae20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ae30 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74  ,N,E,P,0,S,L)] t
2ae40 68 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a  he finializer.**
2ae50 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
2ae60 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73  on L will always
2ae70 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   be invoked exac
2ae80 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a  tly once if the.
2ae90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70  **          step
2aea0 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63   function S is c
2aeb0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2aec0 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  e times..**.** {
2aed0 46 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c  F16142} When SQL
2aee0 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68  ite invokes eith
2aef0 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  er the xFunc or 
2af00 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f  xStep function o
2af10 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  f.**          an
2af20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2af30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2af40 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63  n or aggregate c
2af50 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  reated.**       
2af60 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
2af70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2af80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72  ] or [sqlite3_cr
2af90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2afa0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2afb0 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f  then the array o
2afc0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
2afd0 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64  ] objects passed
2afe0 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
2aff0 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65      third parame
2b000 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b  ter are always [
2b010 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b020 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2b030 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b040 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b050 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b060 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2b070 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2b080 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2b090 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2b0a0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2b0b0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2b0c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2b0d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2b0e0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2b0f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b100 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2b110 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2b120 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2b130 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2b140 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b150 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
2b160 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2b170 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
2b180 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2b190 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2b1a0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2b1b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2b1c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b1d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2b1e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2b1f0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2b200 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2b210 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2b220 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2b230 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b240 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2b250 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
2b260 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a  ings {F10267}.**
2b270 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2b280 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
2b290 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
2b2a0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
2b2b0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
2b2c0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
2b2d0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
2b2e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
2b2f0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2b300 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2b310 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
2b320 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2b330 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
2b340 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2b350 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
2b360 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
2b370 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
2b380 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
2b390 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
2b3a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2b3b0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
2b3c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b3d0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
2b3e0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
2b3f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b400 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
2b410 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65  CAPI3REF: Obsole
2b420 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  te Functions.**.
2b430 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2b440 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f  ns are all now o
2b450 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64  bsolete.  In ord
2b460 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
2b470 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
2b480 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
2b490 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f  lder code, we co
2b4a0 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72  ntinue to suppor
2b4b0 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  t.** these funct
2b4c0 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  ions.  However, 
2b4d0 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20  new development 
2b4e0 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20  projects should 
2b4f0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2b500 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2b510 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2b520 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2b530 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2b540 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2b550 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2b560 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2b570 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  ant they do..*/.
2b580 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2b590 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2b5a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69  te3_context*);.i
2b5b0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
2b5c0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
2b5d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  );.int sqlite3_t
2b5e0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
2b5f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b600 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b610 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
2b620 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
2b630 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  ;.void sqlite3_t
2b640 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
2b650 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
2b660 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2b670 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2b680 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2b690 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2b6a0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2b6b0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
2b6c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
2b6d0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46  ameter Values {F
2b6e0 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  15100}.**.** The
2b6f0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2b700 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2b710 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2b720 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2b730 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2b740 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2b750 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2b760 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2b770 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2b780 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2b790 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2b7a0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2b7b0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2b7c0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2b7d0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2b7e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2b7f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2b800 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2b810 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2b820 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2b830 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2b840 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2b850 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2b860 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
2b870 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2b880 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
2b890 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
2b8a0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2b8b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b8c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2b8d0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2b8e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2b8f0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2b900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2b910 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2b920 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b930 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2b940 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2b950 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2b960 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2b970 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b980 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2b990 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2b9a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2b9b0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2b9c0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2b9d0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2b9e0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2b9f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2ba00 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2ba10 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2ba20 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  avior..**.** The
2ba30 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2ba40 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2ba50 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a  orresponding .**
2ba60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ba70 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2ba80 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65  column_* routine
2ba90 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 0a  s] except that .
2baa0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2bab0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2bac0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2bad0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2bae0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74   pointer.** inst
2baf0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2bb00 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2bb10 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2bb20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2bb30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2bb40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2bb50 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2bb60 74 73 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  ts a UTF16 strin
2bb70 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2bb80 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2bb90 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2bba0 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  e.  The.** sqlit
2bbb0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2bbc0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2bbd0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
2bbe0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
2bbf0 78 74 72 61 63 74 20 55 54 46 31 36 20 73 74 72  xtract UTF16 str
2bc00 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
2bc10 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
2bc20 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
2bc30 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
2bc40 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2bc50 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
2bc60 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2bc70 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
2bc80 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
2bc90 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
2bca0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
2bcb0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
2bcc0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2bcd0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
2bce0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
2bcf0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
2bd00 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
2bd10 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
2bd20 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
2bd30 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
2bd40 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65 20  ** words if the 
2bd50 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
2bd60 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
2bd70 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
2bd80 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
2bd90 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68  on is done.  Oth
2bda0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2bdb0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68  sion occurs.  Th
2bdc0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e .** [SQLITE_IN
2bdd0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2bde0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
2bdf0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  on is returned..
2be00 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2be10 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2be20 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2be30 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2be40 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65  er that.** is re
2be50 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2be60 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2be70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2be80 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
2be90 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2bea0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
2beb0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
2bec0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
2bed0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2bee0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2bef0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2bf00 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
2bf10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2bf20 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2bf30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2bf40 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
2bf50 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2bf60 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2bf70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2bf80 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2bf90 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2bfa0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2bfb0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2bfc0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49  ters..**.**.** I
2bfd0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2bfe0 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73   {F15103} The [s
2bff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2c000 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  b(V)] interface 
2c010 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c020 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c030 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c040 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c050 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e   a blob and then
2c060 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
2c070 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
2c080 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
2c090 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
2c0a0 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5106} The [sqlit
2c0b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56  e3_value_bytes(V
2c0c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2c0d0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2c0e0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2c0f0 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62  ytes in the blob
2c100 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
2c110 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2c120 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2c130 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2c140 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2c150 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2c170 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2c180 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c190 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20  blob(V)] or.**  
2c1a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2c1b0 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e  _value_text(V)].
2c1c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20  .**.** {F15109} 
2c1d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2c1e0 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69  ue_bytes16(V)] i
2c1f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c200 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c210 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c220 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28   in the string (
2c230 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2c240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2c250 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
2c260 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
2c270 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
2c280 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c290 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2c2a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
2c2b0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a  lue_text16(V)],.
2c2c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2c2d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c2e0 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c  6be(V)], or [sql
2c2f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c300 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6le(V)]..**.** {
2c310 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  F15112} The [sql
2c320 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2c330 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2c340 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c350 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c360 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c370 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c380 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2c390 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20  t value and.**  
2c3a0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2c3b0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
2c3c0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  alue..**.** {F15
2c3d0 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  115} The [sqlite
2c3e0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20  3_value_int(V)] 
2c3f0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2c400 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2c410 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2c420 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c430 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d  ect V into a 64-
2c440 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2c450 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
2c460 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
2c470 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
2c480 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2c490 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65  .** {F15118} The
2c4a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c4b0 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66  int64(V)] interf
2c4c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2c4e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c4f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2c500 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2c510 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2c520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2c530 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2c540 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
2c550 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20  ** {F15121} The 
2c560 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2c570 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ext(V)] interfac
2c580 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c590 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c5a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c5b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c5c0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c5d0 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20  ated UTF-8 .**  
2c5e0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2c5f0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2c600 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2c610 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
2c620 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2c630 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29  _value_text16(V)
2c640 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c650 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2c660 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2c670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c680 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2c690 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2c6a0 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2c6b0 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2c6c0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2c6d0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
2c6e0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2c6f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c700 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2c710 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b  * {F15127} The [
2c720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c730 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
2c740 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c750 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c760 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c770 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c780 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2c790 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2c7a0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2c7b0 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
2c7c0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2c7d0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2c7e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c7f0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2c800 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65  .** {F15130} The
2c810 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c820 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
2c830 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c840 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c850 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c860 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c870 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2c880 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2c890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2c8a0 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74  gned UTF-16 litt
2c8b0 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
2c8c0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2c8d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c8e0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2c8f0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33  g..**.** {F15133
2c900 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c910 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e  alue_type(V)] in
2c920 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2c930 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2c940 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2c950 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2c960 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2c970 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2c980 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2c990 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2c9a0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2c9b0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2c9c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c9d0 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a  e] object V..**.
2c9e0 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20  ** {F15136} The 
2c9f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e  [sqlite3_value_n
2ca00 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20  umeric_type(V)] 
2ca10 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2ca20 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ts.**          t
2ca30 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  he [protected sq
2ca40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ca50 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65  ect V into eithe
2ca60 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a  r an integer or.
2ca70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c  **          a fl
2ca80 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ca90 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20  ue if it can do 
2caa0 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  so without loss 
2cab0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  of.**          i
2cac0 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20  nformation, and 
2cad0 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b  returns one of [
2cae0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a  SQLITE_NULL],.**
2caf0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2cb00 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2cb10 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2cb20 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a  ITE_TEXT], or.**
2cb30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2cb40 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2cb50 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2cb60 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
2cb70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cb80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66  lue] object V af
2cb90 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ter the conversi
2cba0 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63  on attempt..*/.c
2cbb0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cbc0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2cbd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2cbe0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2cbf0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2cc00 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2cc10 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2cc20 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2cc30 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2cc40 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2cc50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2cc60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2cc70 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2cc80 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2cc90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2cca0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2ccb0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ccc0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2ccd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cce0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2ccf0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2cd00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2cd10 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2cd20 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2cd30 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2cd40 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2cd50 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2cd60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2cd70 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2cd80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2cd90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2cda0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2cdb0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2cdc0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2cdd0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2cde0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2cdf0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2ce00 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2ce10 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d  Context {F16210}
2ce20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
2ce30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
2ce40 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2ce50 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
2ce60 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2ce70 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
2ce80 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2ce90 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54  ir state.  .** T
2cea0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2ceb0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2cec0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f  ate_context() ro
2ced0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63  utine is.** is c
2cee0 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74  alled for a part
2cef0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2cf00 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
2cf10 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
2cf20 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61  ory.** zeros tha
2cf30 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2cf40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2cf50 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63  to it..** On sec
2cf60 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2cf70 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  nt calls to sqli
2cf80 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2cf90 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74  ntext().** for t
2cfa0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2cfb0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
2cfc0 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  , the same buffe
2cfd0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2cfe0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
2cff0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61  tion.** of the a
2d000 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
2d010 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
2d020 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
2d030 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  te data..**.** S
2d040 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2d050 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c  lly frees the al
2d060 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77  located buffer w
2d070 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2d080 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
2d090 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
2d0a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2d0b0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
2d0c0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   of the .** [sql
2d0d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2d0e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2d0f0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2d100 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
2d110 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2d120 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2d130 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2d140 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
2d150 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2d160 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2d170 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2d180 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2d190 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
2d1a0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2d1b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2d1c0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2d1d0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31  S:.**.** {F16211
2d1e0 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f  } The first invo
2d1f0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
2d200 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d210 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a  text(C,N)] for.*
2d220 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72  *          a par
2d230 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
2d240 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65   of an aggregate
2d250 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61   function (for a
2d260 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20   particular.**  
2d270 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
2d280 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  C) causes SQLite
2d290 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e   to allocation N
2d2a0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
2d2b0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  ,.**          ze
2d2c0 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ro that memory, 
2d2d0 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
2d2e0 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f  nter to the allo
2d2f0 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  cated.**        
2d300 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20    memory..**.** 
2d310 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {F16213} If a me
2d320 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2d330 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2d340 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2d350 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2d360 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2d370 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2d380 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2d390 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63  .** {F16215} Sec
2d3a0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2d3b0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2d3c0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2d3d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d3e0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2d3f0 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2d400 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2d410 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2d420 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2d430 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2d440 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2d450 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2d460 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2d470 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2d480 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2d490 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54  **.** {F16217} T
2d4a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2d4b0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2d4c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d4d0 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2d4e0 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2d4f0 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2d500 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2d510 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2d530 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d540 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2d550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d560 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2d570 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2d580 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2d590 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d5a0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2d5b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2d5c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2d5d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d5e0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2d5f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2d600 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2d610 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a  tions {F16240}.*
2d620 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d630 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2d640 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d650 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2d660 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2d670 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2d680 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2d690 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2d6a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d6b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d6c0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2d6d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d6e0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2d6f0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2d700 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2d710 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2d720 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2d730 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2d740 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2d750 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2d760 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2d770 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
2d780 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d790 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
2d7a0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2d7b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2d7c0 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c  F16243} The [sql
2d7d0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43  ite3_user_data(C
2d7e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2d7f0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2d800 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50  he.**          P
2d810 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2d820 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2d830 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2d840 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2d850 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2d860 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d870 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2d880 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2d890 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2d8a0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2d8b0 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2d8c0 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20  iated with .**  
2d8d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d8e0 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
2d8f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
2d900 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
2d910 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2d920 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
2d930 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
2d940 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  For Functions {F
2d950 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16250}.**.** The
2d960 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2d970 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2d980 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d990 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2d9a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2d9b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d9c0 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2d9d0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2d9e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2d9f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2da00 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2da10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2da20 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2da30 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2da40 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2da50 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2da60 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
2da70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2da80 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54 68  *.** {F16253} Th
2da90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2daa0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d  xt_db_handle(C)]
2dab0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dac0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2dad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70  .**          D p
2dae0 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
2daf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2db00 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2db10 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2db20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2db30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2db40 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
2db50 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
2db60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2db70 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
2db80 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2db90 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20  ted with .**    
2dba0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2dbb0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
2dbc0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2dbd0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2dbe0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dbf0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2dc00 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2dc10 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31  xiliary Data {F1
2dc20 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6270}.**.** The 
2dc30 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
2dc40 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
2dc50 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
2dc60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
2dc70 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
2dc80 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  -data with argum
2dc90 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
2dca0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
2dcb0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
2dcc0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
2dcd0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
2dce0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
2dcf0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
2dd00 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
2dd10 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
2dd20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
2dd30 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20  eta-data may be 
2dd40 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
2dd50 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
2dd60 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
2dd70 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
2dd80 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
2dd90 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
2dda0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
2ddb0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
2ddc0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2ddd0 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
2dde0 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61  s.** meta-data a
2ddf0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2de00 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
2de10 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
2de20 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
2de30 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
2de40 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
2de50 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
2de60 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
2de70 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
2de80 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2de90 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
2dea0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
2deb0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
2dec0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2ded0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
2dee0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
2def0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
2df00 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2df10 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2df20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2df30 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
2df40 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
2df50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
2df60 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
2df70 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
2df80 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
2df90 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
2dfa0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2dfb0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f  nction..** If no
2dfc0 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62   meta-data has b
2dfd0 65 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65  een ever been se
2dfe0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a  t for the Nth.**
2dff0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2e000 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
2e010 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2e020 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
2e030 6d 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61  meter.** has cha
2e040 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
2e050 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
2e060 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  , then sqlite3_g
2e070 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
2e080 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2e090 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
2e0a0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2e0b0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2e0c0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2e0d0 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  -data.** pointed
2e0e0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2e0f0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2e100 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68  meta-data for th
2e110 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
2e120 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
2e130 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e140 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
2e150 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2e160 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e170 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
2e180 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
2e190 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
2e1a0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a  een destroyed. .
2e1b0 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
2e1c0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
2e1d0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2e1e0 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63  tructor .** func
2e1f0 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
2e200 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2e210 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
2e220 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
2e230 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65  he meta-data whe
2e240 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
2e250 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2e260 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
2e270 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
2e280 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2e290 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
2e2a0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
2e2b0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
2e2c0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
2e2d0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
2e2e0 6f 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a  op meta-data on.
2e2f0 2a 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72  ** any parameter
2e300 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2e310 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
2e320 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2e330 65 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65  e.** is that the
2e340 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2e350 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2e360 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2e370 73 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  s.** dropped..**
2e380 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
2e390 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72   meta-data is pr
2e3a0 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
2e3b0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
2e3c0 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
2e3d0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
2e3e0 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
2e3f0 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
2e400 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
2e410 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
2e420 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
2e430 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2e440 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2e450 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2e460 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2e470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2e480 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2e490 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2e4a0 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b  * {F16272} The [
2e4b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e4c0 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  ata(C,N)] interf
2e4d0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2e4e0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
2e4f0 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73    to metadata as
2e500 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2e510 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2e520 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2e530 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
2e540 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73  whose context is
2e550 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74   C, or NULL if t
2e560 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
2e570 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ata associated.*
2e580 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
2e590 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  that parameter..
2e5a0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54  **.** {F16274} T
2e5b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
2e5c0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
2e5d0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69  ] interface assi
2e5e0 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a  gns a metadata.*
2e5f0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2e600 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20  er P to the Nth 
2e610 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2e620 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69   SQL function wi
2e630 74 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  th context.**   
2e640 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20         C..**.** 
2e650 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {F16276} SQLite 
2e660 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2e670 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
2e680 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
2e690 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
2e6a0 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
2e6b0 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
2e6c0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
2e6d0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2e6e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2e6f0 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
2e700 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
2e710 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
2e720 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
2e730 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  ta..**.** {F1627
2e740 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
2e750 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
2e760 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
2e770 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
2e780 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
2e790 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2e7a0 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
2e7b0 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nges..**.** {F16
2e7c0 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
2e7d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2e7e0 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
2e7f0 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
2e800 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
2e810 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
2e820 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
2e830 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2e840 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e850 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
2e860 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
2e870 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
2e880 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {F16279} SQLite 
2e890 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
2e8a0 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
2e8b0 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
2e8c0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
2e8d0 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
2e8e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e8f0 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
2e900 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
2e910 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2e920 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2e930 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
2e940 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
2e950 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e960 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2e970 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
2e980 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
2e990 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2e9a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
2e9b0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
2e9c0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
2e9d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
2e9e0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
2e9f0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
2ea00 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38   Behavior {F1028
2ea10 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  0}.**.** These a
2ea20 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
2ea30 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
2ea40 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
2ea50 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
2ea60 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
2ea70 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2ea80 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ea90 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
2eaa0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
2eab0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
2eac0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
2ead0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2eae0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
2eaf0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
2eb00 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
2eb10 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
2eb20 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
2eb30 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51  yed.  The .** SQ
2eb40 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
2eb50 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
2eb60 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
2eb70 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
2eb80 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
2eb90 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
2eba0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
2ebb0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2ebc0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2ebd0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
2ebe0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2ebf0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
2ec00 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
2ec10 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
2ec20 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
2ec30 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
2ec40 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
2ec50 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
2ec60 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
2ec70 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
2ec80 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
2ec90 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
2eca0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2ecb0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
2ecc0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
2ecd0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
2ece0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2ecf0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
2ed00 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
2ed10 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
2ed20 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36  QL Function {F16
2ed30 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
2ed40 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2ed50 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
2ed60 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2ed70 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
2ed80 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
2ed90 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2eda0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
2edb0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2edc0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2edd0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ede0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
2edf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2ee00 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
2ee10 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
2ee20 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
2ee30 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ke the .** [sqli
2ee40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2ee50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20  sqlite3_bind_*] 
2ee60 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
2ee70 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  ons used.** to b
2ee80 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
2ee90 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
2eea0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2eeb0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
2eec0 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  o the.** [sqlite
2eed0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2eee0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63  lite3_bind_* doc
2eef0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a  umentation] for.
2ef00 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
2ef10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2ef20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ef30 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
2ef40 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2ef50 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2ef60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ef70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2ef80 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
2ef90 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
2efa0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
2efb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2efc0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
2efd0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
2efe0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
2eff0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2f000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f010 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2f020 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
2f030 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2f040 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2f050 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2f060 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
2f070 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
2f080 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
2f090 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
2f0a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2f0b0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
2f0c0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2f0d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f0e0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
2f0f0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2f100 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2f110 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2f120 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f130 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
2f140 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
2f150 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
2f160 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
2f170 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f180 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f190 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2f1a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
2f1b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
2f1c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
2f1d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2f1e0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
2f1f0 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ion..** SQLite u
2f200 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
2f210 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2f220 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
2f230 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
2f240 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
2f250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f260 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
2f270 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
2f280 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c  or message.  SQL
2f290 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
2f2a0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2f2b0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
2f2c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f2d0 72 72 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20  rror() as UTF8. 
2f2e0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2f2f0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2f300 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2f310 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2f320 20 55 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65   UTF16 in native
2f330 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
2f340 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
2f350 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f360 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f370 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f380 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2f390 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
2f3a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
2f3b0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2f3c0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
2f3d0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2f3e0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2f3f0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74  ter..** If the t
2f400 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2f410 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2f420 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
2f430 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f440 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
2f450 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2f460 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
2f470 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
2f480 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
2f490 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2f4a0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
2f4b0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68  r message..** Th
2f4c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f4d0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2f4e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f4f0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
2f500 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72  s make a copy pr
2f510 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2f520 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2f530 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
2f540 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
2f550 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
2f560 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
2f570 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
2f580 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
2f590 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
2f5a0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2f5b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f5c0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2f5d0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2f5e0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2f5f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2f600 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2f610 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2f620 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42  n a function.  B
2f630 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
2f640 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
2f650 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41  SQLITE_ERROR.  A
2f660 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2f670 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2f680 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2f690 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f6a0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
2f6b0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
2f6c0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
2f6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f6e0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
2f6f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2f700 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f  ses SQLite.** to
2f710 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20   throw an error 
2f720 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2f730 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2f740 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74   is to long.** t
2f750 6f 20 72 65 70 72 65 73 65 6e 74 2e 20 20 54 68  o represent.  Th
2f760 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f770 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
2f780 63 65 0a 2a 2a 20 63 61 75 73 65 73 20 53 51 4c  ce.** causes SQL
2f790 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2f7a0 65 78 63 65 70 74 69 6f 6e 20 69 6e 64 69 63 61  exception indica
2f7b0 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 0a  ting that the a.
2f7c0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
2f7d0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
2f7e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f7f0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
2f800 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2f810 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2f820 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2f830 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2f840 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
2f850 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2f860 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2f870 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2f880 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
2f890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2f8a0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
2f8b0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2f8c0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2f8d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f8e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f8f0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
2f900 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2f910 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2f920 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2f930 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f940 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
2f950 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2f960 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2f970 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2f980 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f990 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
2f9a0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
2f9b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f9c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
2f9d0 6c 74 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a  lt_text16(), .**
2f9e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f9f0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
2fa00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fa10 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
2fa20 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
2fa30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2fa40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2fa50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fa60 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
2fa70 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2fa80 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
2fa90 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
2faa0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2fab0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2fac0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
2fad0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
2fae0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2faf0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2fb00 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2fb10 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2fb20 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2fb30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2fb40 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2fb50 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2fb60 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
2fb70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2fb80 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2fb90 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2fba0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2fbb0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2fbc0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2fbd0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2fbe0 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72  arameter .** thr
2fbf0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2fc00 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2fc10 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
2fc20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2fc30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fc40 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2fc50 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2fc60 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2fc70 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2fc80 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2fc90 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2fca0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2fcb0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2fcc0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2fcd0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2fce0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2fcf0 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2fd00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fd10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fd20 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fd30 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fd40 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
2fd50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2fd60 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
2fd70 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
2fd80 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
2fd90 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
2fda0 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68  r blob result wh
2fdb0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
2fdc0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2fdd0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
2fde0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2fdf0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2fe00 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2fe10 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2fe20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2fe30 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2fe40 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2fe50 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a  _STATIC, then.**
2fe60 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2fe70 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
2fe80 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 69 73 20   blob result is 
2fe90 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
2fea0 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63  nd.** does not c
2feb0 6f 70 79 20 74 68 65 20 73 70 61 63 65 20 6f 72  opy the space or
2fec0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
2fed0 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  or when it has.*
2fee0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2fef0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2ff00 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2ff10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2ff20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ff30 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2ff40 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2ff50 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2ff60 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2ff70 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
2ff80 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
2ff90 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2ffa0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
2ffb0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
2ffc0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
2ffd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
2ffe0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
2fff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30000 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30010 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30020 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
30030 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
30040 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30050 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
30060 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
30070 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30080 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
30090 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
300a0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
300b0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
300c0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
300d0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
300e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
300f0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
30100 74 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t [sqlite3_value
30110 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
30120 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
30130 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
30140 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
30150 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
30160 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
30170 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
30180 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
30190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
301a0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
301b0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
301c0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
301d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
301e0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
301f0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
30200 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
30210 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30220 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
30230 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
30240 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
30250 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
30260 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
30270 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
30280 68 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74  hread .** than t
30290 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
302a0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
302b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
302c0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
302d0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
302e0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
302f0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
30300 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
30310 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
30320 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54  **.** {F16403} T
30330 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72  he default retur
30340 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79  n value from any
30350 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
30360 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   NULL..**.** {F1
30370 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  6406} The [sqlit
30380 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
30390 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
303a0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
303b0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
303c0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
303d0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 62 6c  ion C to be a bl
303e0 6f 62 20 74 68 61 74 20 69 73 20 4e 20 62 79 74  ob that is N byt
303f0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  es.**          i
30400 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74  n length and wit
30410 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  h content pointe
30420 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a  d to by V..**.**
30430 20 7b 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73   {F16409} The [s
30440 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
30450 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  uble(C,V)] inter
30460 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30480 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30490 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
304a0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
304b0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
304c0 7b 46 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71  {F16412} The [sq
304d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
304e0 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72  or(C,V,N)] inter
304f0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30500 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
30510 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e      value of fun
30520 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
30530 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
30540 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
30550 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
30560 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 38  RROR] and a UTF8
30570 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
30580 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
30590 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
305a0 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
305b0 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
305c0 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
305d0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
305e0 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68  *.** {F16415} Th
305f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30600 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
30610 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30620 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
30630 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
30640 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30650 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
30660 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
30670 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
30680 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
30690 20 61 20 55 54 46 31 36 20 6e 61 74 69 76 65 20   a UTF16 native 
306a0 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72  byte order error
306b0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
306c0 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d       copied from
306d0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
306e0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
306f0 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  or or until N by
30700 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
30710 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73  are read if N is
30720 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   positive..**.**
30730 20 7b 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73   {F16418} The [s
30740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30750 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69  ror_toobig(C)] i
30760 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30770 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
30780 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
30790 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
307a0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
307b0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
307c0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
307d0 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61  SQLITE_TOOBIG] a
307e0 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
307f0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
30800 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20  .**.** {F16421} 
30810 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30820 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
30830 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
30840 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
30850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
30860 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
30870 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
30880 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
30890 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
308a0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45      [SQLITE_NOME
308b0 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  M] and an approp
308c0 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
308d0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  age..**.** {F164
308e0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
308f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
30900 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61  de(C,E)] interfa
30910 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
30920 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
30930 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
30940 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
30950 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
30960 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a  h error code E..
30970 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20  **          The 
30980 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
30990 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  xt is unchanged.
309a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20  .**.** {F16427} 
309b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
309c0 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e  ult_int(C,V)] in
309d0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
309e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
309f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30a00 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30a10 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65   the 32-bit inte
30a20 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  ger value V..**.
30a30 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20  ** {F16430} The 
30a40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30a50 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65  int64(C,V)] inte
30a60 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30a70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
30a80 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
30a90 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
30aa0 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  he 64-bit intege
30ab0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
30ac0 20 7b 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73   {F16433} The [s
30ad0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
30ae0 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ll(C)] interface
30af0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30b00 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30b10 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30b20 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  n C to be NULL..
30b30 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54  **.** {F16436} T
30b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30b50 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
30b60 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30b70 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30b80 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30b90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30ba0 6f 20 62 65 20 74 68 65 20 55 54 46 38 20 73 74  o be the UTF8 st
30bb0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
30bc0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
30bd0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
30be0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
30bf0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
30c00 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
30c10 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
30c20 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
30c30 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  39} The [sqlite3
30c40 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
30c50 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
30c60 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
30c70 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30c80 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
30c90 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
30ca0 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79 74  UTF16 native byt
30cb0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
30cc0 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
30cd0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
30ce0 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20  o if N is.**    
30cf0 20 20 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f        negative o
30d00 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
30d10 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
30d20 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
30d30 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68  *.** {F16442} Th
30d40 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30d50 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
30d60 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
30d70 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30d80 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30d90 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30da0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31  C to be the UTF1
30db0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
30dc0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
30dd0 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
30de0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
30df0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 65  *          is ne
30e00 67 61 74 69 76 65 20 6f 72 20 74 68 65 20 66 69  gative or the fi
30e10 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56  rst N bytes or V
30e20 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
30e30 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
30e40 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6445} The [sqlit
30e50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30e60 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  le(C,V,N,D)] int
30e70 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
30e80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
30e90 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
30ea0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
30eb0 74 68 65 20 55 54 46 31 36 20 6c 69 74 74 6c 65  the UTF16 little
30ec0 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
30ed0 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
30ee0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
30ef0 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20  o if N is.**    
30f00 20 20 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f        negative o
30f10 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
30f20 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
30f30 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
30f40 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68  *.** {F16448} Th
30f50 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30f60 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e  t_value(C,V)] in
30f70 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30f80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30f90 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30fa0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30fb0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
30fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
30fd0 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
30fe0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31  V..**.** {F16451
30ff0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31000 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
31010 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
31020 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
31030 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
31040 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
31050 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74  C to be an N-byt
31060 65 20 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65  e blob of all ze
31070 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ros..**.** {F164
31080 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  54} The [sqlite3
31090 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d  _result_error()]
310a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
310b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a  sult_error16()].
310c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
310d0 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f  rfaces make a co
310e0 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f  py of their erro
310f0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
31100 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  s before.**     
31110 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a       returning..
31120 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49  **.** {F16457} I
31130 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
31140 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
31150 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31160 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
31170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
31180 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31190 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
311a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
311b0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
311c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
311d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
311e0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
311f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31200 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31210 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
31220 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20  is the constant 
31230 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a  [SQLITE_STATIC].
31240 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
31250 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69   no destructor i
31260 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e  s ever called on
31270 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61   the pointer V a
31280 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  nd SQLite.**    
31290 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68        assumes th
312a0 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c  at V is immutabl
312b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30  e..**.** {F16460
312c0 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
312d0 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
312e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
312f0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
31300 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
31310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31320 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
31330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31340 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
31350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31370 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
31380 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
31390 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
313a0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
313b0 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
313c0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nt.**          [
313d0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
313e0 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72  ] then the inter
313f0 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f  faces makes a co
31400 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
31410 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66        content of
31420 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74   V and retains t
31430 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b  he copy..**.** {
31440 46 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44  F16463} If the D
31450 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
31460 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
31470 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
31480 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
31490 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
314a0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
314b0 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
314c0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
314d0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
314e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
314f0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
31500 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
31510 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
31520 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
31530 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65  ,V,N,D)] is some
31540 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
31550 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
31560 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
31570 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20  ITE_STATIC] and 
31580 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
31590 54 5d 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20  T] then .**     
315a0 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c       SQLite will
315b0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
315c0 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20  ructor D with V 
315d0 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  as its only argu
315e0 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
315f0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
31600 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56  ished with the V
31610 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20   value..*/.void 
31620 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
31630 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
31640 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
31650 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
31660 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
31670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
31680 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
31690 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
316a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
316b0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
316c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
316d0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
316e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
316f0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
31700 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31710 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
31720 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31730 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
31740 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31750 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31760 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
31770 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
31780 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
31790 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
317a0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
317b0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
317c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
317d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
317e0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
317f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31800 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
31810 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
31820 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
31830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
31840 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
31850 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
31860 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
31870 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
31890 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
318a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
318b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
318c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
318d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
318e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
318f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31900 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
31910 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31920 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31930 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
31940 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
31950 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
31960 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31970 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
31980 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
31990 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
319a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
319b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
319c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
319d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
319e0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
319f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31a00 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
31a10 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
31a20 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
31a30 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30  equences {F16600
31a40 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  }.**.** These fu
31a50 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
31a60 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
31a70 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
31a80 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  to the.** [sqlit
31a90 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63  e3*] handle spec
31aa0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
31ab0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a  st argument. .**
31ac0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
31ad0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
31ae0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
31af0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
31b00 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
31b10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31b20 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
31b30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
31b40 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
31b50 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
31b60 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
31b70 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31b80 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61  n16(). In all ca
31b90 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
31ba0 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
31bb0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
31bc0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
31bd0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
31be0 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
31bf0 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
31c00 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
31c10 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
31c20 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  E] or [SQLITE_UT
31c30 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
31c40 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
31c50 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
31c60 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
31c70 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
31c80 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
31c90 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
31ca0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
31cb0 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54  tle-endian or UT
31cc0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20  F-16 big-endian 
31cd0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
31ce0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
31cf0 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
31d00 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
31d10 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
31d20 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
31d30 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
31d40 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
31d50 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
31d60 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
31d70 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  TF16 in the nati
31d80 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66  ve byte order of
31d90 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
31da0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  er..**.** A poin
31db0 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20  ter to the user 
31dc0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
31dd0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
31de0 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20  as the fifth.** 
31df0 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74  argument.  If it
31e00 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
31e10 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
31e20 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
31e30 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
31e40 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
31e50 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
31e60 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63  anymore)..** Eac
31e70 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69  h time the appli
31e80 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  cation.** suppli
31e90 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
31ea0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
31eb0 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
31ec0 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
31ed0 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68  as.** the fourth
31ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
31ef0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31f00 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71  ation() or.** sq
31f10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31f20 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74  lation16() as it
31f30 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
31f40 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  r..**.** The rem
31f50 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
31f60 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
31f70 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
31f80 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
31f90 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
31fa0 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
31fb0 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
31fc0 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
31fd0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
31fe0 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
31ff0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
32000 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
32010 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
32020 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
32030 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65  tered. {END} The
32040 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32050 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
32060 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
32070 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
32080 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
32090 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72  ve if.** the fir
320a0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
320b0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
320c0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
320d0 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  n the second.** 
320e0 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
320f0 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
32100 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
32110 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32120 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
32130 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
32140 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
32150 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
32160 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
32170 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
32180 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
32190 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
321a0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
321b0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
321c0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
321d0 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
321e0 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
321f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
32200 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
32210 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
32220 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
32230 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32240 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74  _v2()..** Collat
32250 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
32260 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20  ed when.** they 
32270 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
32280 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
32290 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
322a0 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
322b0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
322c0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
322d0 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63  base handle is c
322e0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
322f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
32300 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
32310 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20  .**.** {F16603} 
32320 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
32330 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  l to the.**     
32340 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
32350 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
32360 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20  2(B,X,E,P,F,D)] 
32370 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20  interface.**    
32380 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20        registers 
32390 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68  function F as th
323a0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
323b0 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a  ction used to.**
323c0 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d            implem
323d0 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20  ent collation X 
323e0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
323f0 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
32400 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
32410 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
32420 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ding E..**.** {F
32430 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
32440 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
32450 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
32460 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32470 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32480 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
32490 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
324a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
324b0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
324c0 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
324d0 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
324e0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
324f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
32500 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
32510 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
32520 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
32530 46 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  F16606} Successi
32540 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
32550 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32560 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
32570 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
32580 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
32590 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
325a0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
325b0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
325c0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
325d0 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
325e0 20 7b 46 31 36 36 30 39 7d 20 54 68 65 20 64 65   {F16609} The de
325f0 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73  structor D in [s
32600 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32610 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
32620 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
32630 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c       is not NULL
32640 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c   then it is call
32650 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
32660 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20   P when the.**  
32670 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
32680 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
32690 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e  opped by SQLite.
326a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20  .**.** {F16612} 
326b0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
326c0 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
326d0 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c  when it is overl
326e0 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  oaded..**.** {F1
326f0 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6615} A collatin
32700 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
32710 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64  opped when the d
32720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32730 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
32740 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
32750 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
32760 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d  ..**.** {F16618}
32770 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69   The pointer P i
32780 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
32790 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
327a0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
327b0 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73           is pass
327c0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
327d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
327e0 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69  r to the compari
327f0 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
32800 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
32810 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
32820 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a  vocations of F..
32830 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41  **.** {F16621} A
32840 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
32850 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32860 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69  on(B,X,E,P,F)] i
32870 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
32880 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
32890 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  s a call to [sql
328a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
328b0 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68  ation_v2()] with
328c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
328d0 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73   same parameters
328e0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74   and a NULL dest
328f0 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ructor..**.** {F
32900 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67  16624} Following
32910 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61   a [sqlite3_crea
32920 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32930 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a  B,X,E,P,F,D)],.*
32940 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
32950 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61  e uses the compa
32960 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46  rison function F
32970 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f   for all text co
32980 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
32990 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20       operations 
329a0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
329b0 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65  nection] B on te
329c0 78 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a  xt values that.*
329d0 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74  *          use t
329e0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  he collating seq
329f0 75 65 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a  uence name X..**
32a00 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20 54 68 65  .** {F16627} The
32a10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32a20 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58  _collation16(B,X
32a30 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74  ,E,P,F)] works t
32a40 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
32a50 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f      as [sqlite3_
32a60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32a70 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63  (B,X,E,P,F)] exc
32a80 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ept that the.** 
32a90 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
32aa0 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64  on name X is und
32ab0 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31  erstood as UTF-1
32ac0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
32ad0 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
32ae0 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54     instead of UT
32af0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  F-8..**.** {F166
32b00 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  30} When multipl
32b10 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
32b20 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ctions are avail
32b30 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d  able for the sam
32b40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
32b50 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
32b60 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73  , SQLite chooses
32b70 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74   the one whose t
32b80 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
32b90 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65           require
32ba0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
32bb0 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  nt of conversion
32bc0 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c   from the defaul
32bd0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  t.**          te
32be0 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  xt encoding of t
32bf0 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
32c00 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32c10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
32c20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
32c30 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
32c40 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32c50 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
32c60 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
32c70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
32c80 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
32c90 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
32ca0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32cb0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
32cc0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
32cd0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
32ce0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
32cf0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
32d00 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
32d10 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
32d20 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
32d30 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
32d40 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
32d50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32d60 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
32d70 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
32d80 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
32d90 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
32da0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
32db0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
32dc0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
32dd0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
32de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32df0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
32e00 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ed Callbacks {F1
32e10 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  6700}.**.** To a
32e20 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
32e30 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
32e40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
32e50 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
32e60 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
32e70 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
32e80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
32e90 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
32ea0 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
32eb0 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
32ec0 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
32ed0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
32ee0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32ef0 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
32f00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
32f10 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
32f20 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
32f30 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
32f40 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
32f50 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
32f60 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
32f70 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
32f80 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
32f90 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
32fa0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b  oded in UTF-8. {
32fb0 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74  F16703} If sqlit
32fc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
32fd0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
32fe0 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72   the names.** ar
32ff0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
33000 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
33010 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
33020 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
33030 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
33040 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74  places any exist
33050 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ing callback..**
33060 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
33070 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
33080 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
33090 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
330a0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
330b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
330c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
330d0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
330e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
330f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33100 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
33110 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
33120 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65  tabase.** handle
33130 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
33140 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
33150 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
33160 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  * [SQLITE_UTF16B
33170 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
33180 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
33190 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20  ing the most.** 
331a0 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
331b0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
331c0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
331d0 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54  n required..** T
331e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
331f0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
33200 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
33210 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
33220 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
33230 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
33240 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
33250 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
33260 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
33270 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
33280 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
33290 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
332a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
332b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
332c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
332d0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
332e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
332f0 46 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73  F16702} A succes
33300 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
33310 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33320 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a  needed(D,P,F)].*
33330 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
33340 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33350 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29  _needed16(D,P,F)
33360 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20  ] causes.**     
33370 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
33380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
33390 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62   to invoke callb
333a0 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74  ack F with first
333b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
333c0 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
333d0 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d  r it needs a com
333e0 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
333f0 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20   for a.**       
33400 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
33410 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f  uence that it do
33420 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75  es not know abou
33430 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34  t..**.** {F16704
33440 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75  } Each successfu
33450 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33460 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33470 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ded()] or.**    
33480 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
33490 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
334a0 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  6()] overrides t
334b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69  he callback regi
334c0 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
334d0 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
334e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
334f0 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61  ion] by prior ca
33500 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  lls to either.**
33510 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
33520 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  ace..**.** {F167
33530 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  06} The name of 
33540 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f  the requested co
33550 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33560 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a   passed in the.*
33570 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70  *          4th p
33580 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33590 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55  callback is in U
335a0 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c  TF-8 if the call
335b0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
335c0 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20   was registered 
335d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
335e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
335f0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
33600 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20     is in UTF-16 
33610 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33620 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r if the callbac
33630 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  k was.**        
33640 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69    registered usi
33650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
33660 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33670 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74  ]..**.** .*/.int
33680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33690 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
336a0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
336b0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
336c0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
336d0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
336e0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
336f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33700 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
33710 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
33720 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
33730 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
33740 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
33750 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
33760 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
33770 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
33780 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
33790 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
337a0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
337b0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
337c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
337d0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
337e0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
337f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
33800 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
33810 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
33820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
33830 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
33840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33850 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
33860 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
33870 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
33880 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
33890 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
338a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
338b0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
338c0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
338d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
338e0 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
338f0 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
33900 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
33910 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
33920 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
33930 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
33940 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
33950 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
33960 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
33970 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
33980 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
33990 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
339a0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
339b0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
339c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
339d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
339e0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
339f0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
33a00 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
33a10 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
33a20 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
33a30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33a40 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
33a50 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
33a60 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d  rt Time {F10530}
33a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33a80 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
33a90 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68  ion.** causes th
33aa0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
33ab0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
33ac0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
33ad0 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
33ae0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
33af0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
33b00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
33b10 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
33b20 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
33b30 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
33b40 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a  requests with .*
33b50 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
33b60 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
33b70 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
33b80 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
33b90 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65  to .** the neare
33ba0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
33bb0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
33bc0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
33bd0 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75  ctually .** requ
33be0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
33bf0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
33c00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
33c10 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
33c20 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
33c30 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
33c40 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
33c50 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
33c60 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
33c70 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
33c80 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
33c90 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20  ** {F10533} The 
33ca0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
33cb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76  )] interface inv
33cc0 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a  okes the xSleep.
33cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68  **          meth
33ce0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
33cf0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56  t [sqlite3_vfs|V
33d00 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  FS] in order to.
33d10 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70  **          susp
33d20 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  end execution of
33d30 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
33d40 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74  ead for at least
33d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d  .**          M m
33d60 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a  illiseconds..**.
33d70 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68 65 20  ** {F10536} The 
33d80 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
33d90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
33da0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
33db0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  of.**          m
33dc0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
33dd0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65  leep actually re
33de0 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f  quested of the o
33df0 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20  perating.**     
33e00 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69       system, whi
33e10 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  ch might be larg
33e20 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61  er than the para
33e30 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20  meter M..*/.int 
33e40 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
33e50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
33e60 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68  REF:  Name Of Th
33e70 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
33e80 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
33e90 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F10310}.**.** 
33ea0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
33eb0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
33ec0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
33ed0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
33ee0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
33ef0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
33f00 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
33f10 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
33f20 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
33f30 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
33f40 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
33f50 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
33f60 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
33f70 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  s NULL pointer, 
33f80 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73  then SQLite does
33f90 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
33fa0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d   appropriate tem
33fb0 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64  porary.** file d
33fc0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
33fd0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
33fe0 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  o modify this va
33ff0 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61  riable once a da
34000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34010 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70  n.** has been op
34020 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74  ened.  It is int
34030 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
34040 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
34050 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
34060 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
34070 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
34080 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
34090 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
340a0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
340b0 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20  call and remain 
340c0 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61  unchanged therea
340d0 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  fter..*/.SQLITE_
340e0 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
340f0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
34100 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
34110 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53  3REF:  Test To S
34120 65 65 20 49 66 20 54 68 65 20 44 61 74 61 62 61  ee If The Databa
34130 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f  se Is In Auto-Co
34140 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32 39 33  mmit Mode {F1293
34150 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
34160 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
34170 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
34180 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
34190 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
341a0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
341b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
341c0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
341d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
341e0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
341f0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
34200 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66   is on.** by def
34210 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  ault.  Autocommi
34220 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
34230 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
34240 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
34250 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
34260 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
34270 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
34280 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
34290 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
342a0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
342b0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
342c0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
342d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
342e0 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20  actions (errors 
342f0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
34300 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
34310 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51  _IOERR], .** [SQ
34320 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
34330 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
34340 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
34350 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
34360 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
34370 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
34380 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
34390 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
343a0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20  .** find out if 
343b0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
343c0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
343d0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
343e0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
343f0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
34400 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
34410 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
34420 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54 68 65  .** {F12931} The
34430 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
34440 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74  tocommit(D)] int
34450 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
34460 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20  on-zero or.**   
34470 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74         zero if t
34480 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34490 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72  nection] D is or
344a0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
344b0 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  ommit.**        
344c0 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69    mode, respecti
344d0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  vely..**.** {F12
344e0 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  932} Autocommit 
344f0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
34500 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fault..**.** {F1
34510 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2933} Autocommit
34520 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
34530 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75  d by a successfu
34540 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  l [BEGIN] statem
34550 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ent..**.** {F129
34560 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  34} Autocommit m
34570 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
34580 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
34590 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
345a0 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  BACK].**        
345b0 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20    statement..** 
345c0 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
345d0 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39  NS:.***.** {U129
345e0 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74  36} If another t
345f0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
34600 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
34610 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
34620 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
34630 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
34640 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
34650 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
34660 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
34670 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
34680 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
34690 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
346a0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
346b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
346c0 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61  EF:  Find The Da
346d0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
346e0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
346f0 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a  ement {F13120}.*
34700 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34710 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
34720 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
34730 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64  the [sqlite3*] d
34740 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
34750 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72  o which a.** [pr
34760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34770 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68  ] belongs..** Th
34780 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
34790 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
347a0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a  lite3_db_handle.
347b0 2a 2a 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  ** is the same d
347c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
347d0 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66  hat was.** the f
347e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
347f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
34800 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
34810 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74  ts variants.** t
34820 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20  hat was used to 
34830 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
34840 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
34850 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  t place..**.** I
34860 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
34870 20 7b 46 31 33 31 32 33 7d 20 54 68 65 20 5b 73   {F13123} The [s
34880 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
34890 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
348a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
348b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
348c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
348d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
348e0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20  ated with.**    
348f0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
34900 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
34910 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
34920 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
34930 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
34940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46 69  ** CAPI3REF:  Fi
34950 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
34960 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b  ared statement {
34970 46 31 33 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13140}.**.** Re
34980 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
34990 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
349a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
349b0 61 66 74 65 72 20 70 53 74 6d 74 0a 2a 2a 20 61  after pStmt.** a
349c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
349d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
349e0 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53  ion] pDb.  If pS
349f0 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
34a00 68 65 6e 20 72 65 74 75 72 6e 20 61 20 70 6f 69  hen return a poi
34a10 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
34a20 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
34a30 65 6d 65 6e 74 5d 20 61 73 73 6f 63 69 61 74 65  ement] associate
34a40 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
34a50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34a60 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 6e 6f 20  on] pDb.  If no 
34a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34a80 65 6e 74 5d 0a 2a 2a 20 73 61 74 69 73 66 69 65  ent].** satisfie
34a90 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
34aa0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
34ab0 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a  , return NULL..*
34ac0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34ad0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34 33 7d 20  .**.** {F13143} 
34ae0 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62  If D is a [datab
34af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34b00 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f  that holds one o
34b10 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
34b20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b     unfinalized [
34b30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34b40 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20  nts] and S is a 
34b50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a  NULL pointer,.**
34b60 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
34b70 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
34b80 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65  t(D, S)] routine
34b90 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20   shall return a 
34ba0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
34bb0 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68      to one of th
34bc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
34bd0 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74  ements] associat
34be0 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a  ed with D..**.**
34bf0 20 7b 46 31 33 31 34 36 7d 20 49 66 20 44 20 69   {F13146} If D i
34c00 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
34c10 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68  nnection] that h
34c20 6f 6c 64 73 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  olds no.**      
34c30 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20      unfinalized 
34c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34c50 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61  ents] and S is a
34c60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a   NULL pointer,.*
34c70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
34c80 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
34c90 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e  mt(D, S)] routin
34ca0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
34cb0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
34cc0 20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a    pointer..**.**
34cd0 20 7b 46 31 33 31 34 39 7d 20 49 66 20 53 20 69   {F13149} If S i
34ce0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
34cf0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 5b 64 61 74  atement] in [dat
34d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34d10 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
34d20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65  and S is not the
34d30 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 20   last [prepared 
34d40 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 44 2c  statement] in D,
34d50 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
34d60 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f    [sqlite3_next_
34d70 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
34d80 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
34d90 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
34da0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65         to the ne
34db0 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
34dc0 74 65 6d 65 6e 74 5d 20 69 6e 20 44 20 61 66 74  tement] in D aft
34dd0 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  er S..**.** {F13
34de0 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68 65  152} If S is the
34df0 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 20   last [prepared 
34e00 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 5b 64  statement] in [d
34e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e20 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
34e30 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
34e40 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d  next_stmt(D, S)]
34e50 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
34e60 65 74 75 72 6e 20 61 20 4e 55 4c 4c 0a 2a 2a 20  eturn a NULL.** 
34e70 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
34e80 2e 0a 2a 2a 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ..**.*/.sqlite3_
34e90 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
34ea0 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
34eb0 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
34ec0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 0a 2f 2a  mt *pStmt);.../*
34ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34ee0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
34ef0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
34f00 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 35 30  allbacks {F12950
34f10 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
34f20 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
34f30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
34f40 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
34f50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
34f60 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
34f70 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
34f80 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
34f90 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
34fa0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
34fb0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
34fc0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
34fd0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
34fe0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34ff0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
35000 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  n..** The sqlite
35010 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
35020 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
35030 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
35040 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
35050 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
35060 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
35070 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
35080 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
35090 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
350a0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
350b0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
350c0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
350d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
350e0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
350f0 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61  n..** The pArg a
35100 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
35110 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20  d through.** to 
35120 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49  the callback.  I
35130 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
35140 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
35150 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74  function .** ret
35160 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35170 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
35180 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
35190 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
351a0 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
351b0 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
351c0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
351d0 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61  , its.** pArg va
351e0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
351f0 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
35200 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35210 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20  .** Registering 
35220 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
35230 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
35240 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  lback..**.** For
35250 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
35260 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
35270 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
35280 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a 2a   to have been .*
35290 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
352a0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
352b0 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
352c0 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
352d0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
352e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
352f0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
35300 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
35310 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
35320 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
35330 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
35340 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
35350 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
35360 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
35370 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
35380 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
35390 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  osed..** The rol
353a0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
353b0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
353c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
353d0 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  s.** rolled back
353e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69   because a commi
353f0 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  t callback retur
35400 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a  ned non-zero..**
35410 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e   <todo> Check on
35420 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a   this </todo>.**
35430 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65 78  .** These are ex
35440 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72  perimental inter
35450 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73 75  faces and are su
35460 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e  bject to change.
35470 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
35480 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31  S:.**.** {F12951
35490 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
354a0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
354b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
354c0 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
354d0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
354e0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
354f0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
35500 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
35510 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
35520 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
35530 69 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  its on [database
35540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
35550 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54  **.** {F12952} T
35560 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
35570 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
35580 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35590 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20  s the P.**      
355a0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f      argument fro
355b0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
355c0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
355d0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  e .**          [
355e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
355f0 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c  ion ] D , or NUL
35600 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63  L on the first c
35610 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
35620 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
35630 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35640 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
35650 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20 63 61  {F12953} Each ca
35660 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
35670 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76  ommit_hook()] ov
35680 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
35690 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
356a0 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
356b0 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
356c0 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66 20 74  ** {F12954} If t
356d0 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
356e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
356f0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73  _hook(D,F,P)] is
35700 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
35710 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69    then the commi
35720 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
35730 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20  is canceled and 
35740 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
35750 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
35760 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
35770 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a  ction commits..*
35780 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66  *.** {F12955} If
35790 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c   the commit call
357a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
357b0 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63  -zero then the c
357c0 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20  ommit is.**     
357d0 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69       converted i
357e0 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
357f0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54  **.** {F12961} T
35800 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
35810 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
35820 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
35830 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
35840 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
35850 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
35860 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
35870 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
35880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
35890 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73  ransaction rolls
358a0 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61   back on [databa
358b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
358c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d  ..**.** {F12962}
358d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f   The [sqlite3_ro
358e0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
358f0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
35900 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20  turns the P.**  
35910 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
35920 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
35930 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65  us call with the
35940 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20   same .**       
35950 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
35960 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72  nection ] D , or
35970 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
35980 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
35990 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
359a0 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20 63  ular [database c
359b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
359c0 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63  .** {F12963} Eac
359d0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
359e0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
359f0 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
35a00 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
35a10 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
35a20 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
35a30 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34  s..**.** {F12964
35a40 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
35a50 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
35a60 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
35a70 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
35a80 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
35a90 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
35aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
35ab0 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
35ac0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
35ad0 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
35ae0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
35af0 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76  rolls back..*/.v
35b00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
35b10 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
35b20 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
35b30 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
35b40 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
35b50 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
35b60 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
35b70 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
35b80 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
35b90 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
35ba0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
35bb0 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2970}.**.** The 
35bc0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
35bd0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ook() interface.
35be0 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ** registers a c
35bf0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35c00 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
35c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
35c20 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
35c30 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
35c40 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
35c50 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
35c60 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
35c70 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
35c80 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
35c90 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
35ca0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
35cb0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
35cc0 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61   same .** databa
35cd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35ce0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
35cf0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
35d00 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
35d10 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
35d20 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
35d30 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20  en a .** row is 
35d40 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
35d50 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a  d or deleted. .*
35d60 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
35d70 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
35d80 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70  back is.** a cop
35d90 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
35da0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
35db0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
35dc0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
35dd0 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67  callback .** arg
35de0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
35df0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
35e00 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
35e10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
35e20 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  TE],.** dependin
35e30 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
35e40 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
35e50 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
35e60 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68  e invoked..** Th
35e70 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20  e third and .** 
35e80 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
35e90 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
35ea0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
35eb0 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
35ec0 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20  e and .** table 
35ed0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
35ee0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
35ef0 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63  ..** The final c
35f00 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
35f10 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77  r is .** the row
35f20 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  id of the row..*
35f30 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  * In the case of
35f40 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
35f50 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66   is the rowid af
35f60 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61  ter .** the upda
35f70 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
35f80 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
35f90 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
35fa0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
35fb0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
35fc0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
35fd0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
35fe0 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
35ff0 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  sequence)..**.**
36000 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
36010 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
36020 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
36030 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
36040 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
36050 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
36060 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36070 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
36080 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65  .** {F12971} The
36090 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
360a0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
360b0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63  terface causes c
360c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
360d0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74      function F t
360e0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
360f0 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  h first paramete
36100 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  r P whenever.** 
36110 20 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65           a table
36120 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64   row is modified
36130 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64  , inserted, or d
36140 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  eleted on.**    
36150 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
36160 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
36170 2a 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68  *.** {F12973} Th
36180 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
36190 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
361a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
361b0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
361c0 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20         of P for 
361d0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
361e0 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  l on the same [d
361f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36200 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
36210 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74     or NULL for t
36220 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a  he first call..*
36230 2a 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66  *.** {F12975} If
36240 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
36250 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b   callback F in [
36260 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36270 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20  ook(D,F,P)].**  
36280 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20          is NULL 
36290 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
362a0 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
362b0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   made..**.** {F1
362c0 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20  2977} Each call 
362d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  to [sqlite3_upda
362e0 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
362f0 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20  overrides prior 
36300 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
36310 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e    to the same in
36320 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73  terface on the s
36330 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
36340 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
36350 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20  ** {F12979} The 
36360 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c  update hook call
36370 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
36380 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
36390 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20  l system.**     
363a0 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68       tables such
363b0 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
363c0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
363d0 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
363e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38  ed..**.** {F1298
363f0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
36400 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75  rameter to the u
36410 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a  pdate callback .
36420 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f  **          is o
36430 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
36440 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
36450 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54  ELETE] or [SQLIT
36460 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20  E_UPDATE],.**   
36470 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67         depending
36480 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
36490 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
364a0 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65  e callback to be
364b0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
364c0 7b 46 31 32 39 38 33 7d 20 54 68 65 20 74 68 69  {F12983} The thi
364d0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
364e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
364f0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
36500 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20  pointers.**     
36510 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72       to zero-ter
36520 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
36530 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20  rings which are 
36540 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
36550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
36560 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
36570 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70  that is being up
36580 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39  dated...** {F129
36590 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61  85} The final ca
365a0 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
365b0 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66   is the rowid of
365c0 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a   the row after.*
365d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
365e0 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f  hange occurs..*/
365f0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
36600 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
36610 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
36620 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
36630 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
36640 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
36650 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
36660 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
36670 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20  REF:  Enable Or 
36680 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
36690 61 67 65 72 20 43 61 63 68 65 20 7b 46 31 30 33  ager Cache {F103
366a0 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  30}.**.** This r
366b0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
366c0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
366d0 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
366e0 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
366f0 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
36700 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
36710 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74  en connections t
36720 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
36730 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20  ase..** Sharing 
36740 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
36750 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
36760 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ue and disabled 
36770 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  if the argument.
36780 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  ** is false..**.
36790 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
367a0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
367b0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
367c0 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
367d0 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73  s. {END} This is
367e0 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20   a change as of 
367f0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
36800 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f  .5.0..** In prio
36810 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
36820 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61  Lite, sharing wa
36830 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
36840 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
36850 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
36860 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
36870 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
36880 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
36890 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
368a0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
368b0 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
368c0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
368d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
368e0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
368f0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
36900 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
36910 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
36920 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
36930 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
36940 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
36950 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
36960 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
36970 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
36980 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
36990 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
369a0 61 63 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61  ache.   When sha
369b0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
369c0 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
369d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
369e0 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20  ule()] API used 
369f0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76  to register.** v
36a00 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69  irtual tables wi
36a10 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
36a20 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
36a30 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
36a40 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
36a50 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
36a60 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  e was.** enabled
36a70 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
36a80 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
36a90 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69  error code].** i
36aa0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
36ab0 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72  wise..**.** Shar
36ac0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
36ad0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
36ae0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
36af0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
36b00 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
36b10 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
36b20 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
36b30 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
36b40 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
36b50 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
36b60 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  icitly..**.** IN
36b70 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a  VARIANTS:.** .**
36b80 20 7b 46 31 30 33 33 31 7d 20 41 20 73 75 63 63   {F10331} A succ
36b90 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
36ba0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e  n of [sqlite3_en
36bb0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
36bc0 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  e(B)].**        
36bd0 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72    will enable or
36be0 20 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20   disable shared 
36bf0 63 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61  cache mode for a
36c00 6e 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a  ny subsequently.
36c10 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61  **          crea
36c20 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ted [database co
36c30 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65  nnection] in the
36c40 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a   same process..*
36c50 2a 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68  *.** {F10336} Wh
36c60 65 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20  en shared cache 
36c70 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20  is enabled, the 
36c80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36c90 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  module()].**    
36ca0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
36cb0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
36cc0 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  rn an error..**.
36cd0 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20  ** {F10337} The 
36ce0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
36cf0 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d  shared_cache(B)]
36d00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36d10 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
36d20 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
36d30 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
36d40 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
36d50 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
36d60 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20  .**.** {F10339} 
36d70 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
36d80 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
36d90 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ult..*/.int sqli
36da0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
36db0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
36dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
36dd0 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20  Attempt To Free 
36de0 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37  Heap Memory {F17
36df0 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  340}.**.** The s
36e00 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
36e10 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
36e20 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
36e30 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
36e40 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
36e50 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
36e60 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
36e70 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  y.** allocations
36e80 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
36e90 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b  abase library. {
36ea0 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65  END}  Memory use
36eb0 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61  d.** to cache da
36ec0 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f 20  tabase pages to 
36ed0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
36ee0 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
36ef0 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65  e of.** non-esse
36f00 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53  ntial memory.  S
36f10 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
36f20 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a  emory() returns.
36f30 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
36f40 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
36f50 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67  freed, which mig
36f60 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
36f70 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61  ss.** than the a
36f80 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
36f90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
36fa0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31  S:.**.** {F17341
36fb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
36fc0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29  elease_memory(N)
36fd0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ] interface atte
36fe0 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  mpts to.**      
36ff0 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65 73      free N bytes
37000 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
37010 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
37020 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a  non-essential.**
37030 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
37040 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c   allocations hel
37050 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
37060 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  e library..**.**
37070 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73   {F16342} The [s
37080 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37090 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e  emory(N)] return
370a0 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  s the number.** 
370b0 20 20 20 20 20 20 20 20 20 6f 66 20 62 79 74 65           of byte
370c0 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
370d0 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
370e0 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a   more or less.**
370f0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 74            than t
37100 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
37110 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
37120 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37130 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
37140 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73  CAPI3REF:  Impos
37150 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
37160 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a  p Size {F17350}.
37170 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
37180 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37190 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  t() interface.**
371a0 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
371b0 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
371c0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
371d0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
371e0 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20  allocated.** by 
371f0 53 51 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e  SQLite. If an in
37200 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f  ternal allocatio
37210 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a  n is requested .
37220 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ** that would ex
37230 63 65 65 64 20 74 68 65 20 73 6f 66 74 20 68 65  ceed the soft he
37240 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
37250 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
37260 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  y()] is.** invok
37270 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
37280 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
37290 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
372a0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
372b0 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a  .** is made..**.
372c0 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  ** The limit is 
372d0 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
372e0 65 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71  ecause if.** [sq
372f0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37300 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a  mory()] cannot.*
37310 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  * free sufficien
37320 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
37330 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
37340 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
37350 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
37360 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
37370 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
37380 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
37390 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41  roceeds..**.** A
373a0 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
373b0 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
373c0 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
373d0 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
373e0 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
373f0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37400 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
37410 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
37420 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
37430 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ted..** The defa
37440 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
37450 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37460 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
37470 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
37480 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
37490 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
374a0 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42  ap limit.  .** B
374b0 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68  ut if the soft h
374c0 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74  eap limit cannot
374d0 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65   be honored, exe
374e0 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63  cution will.** c
374f0 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20  ontinue without 
37500 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63  error or notific
37510 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20  ation.  This is 
37520 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73  why the limit is
37530 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73   .** called a "s
37540 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
37550 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
37560 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
37570 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
37580 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
37590 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
375a0 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
375b0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
375c0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
375d0 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
375e0 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
375f0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
37600 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
37610 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
37620 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
37630 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
37640 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
37650 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c  threads. The val
37660 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
37670 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37680 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
37690 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
376a0 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
376b0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
376c0 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20   threads. In.** 
376d0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
376e0 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
376f0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
37700 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap usage 
37710 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61  for.** individua
37720 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a  l threads..**.**
37730 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
37740 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20  ** {F16351} The 
37750 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
37760 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74  ap_limit(N)] int
37770 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
37780 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20  soft limit.**   
37790 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65         of N byte
377a0 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  s on the amount 
377b0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
377c0 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
377d0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
377e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
377f0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
37800 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
37810 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a   at any point.**
37820 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d            in tim
37830 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32  e..**.** {F16352
37840 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
37850 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
37860 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
37870 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a  alloc()] would.*
37880 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73 65  *          cause
37890 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e   the total amoun
378a0 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d  t of allocated m
378b0 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20  emory to exceed 
378c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
378d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
378e0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
378f0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
37900 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
37910 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74          in an at
37920 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20  tempt to reduce 
37930 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  the memory usage
37940 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65   prior to procee
37950 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
37960 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79   with the memory
37970 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65   allocation atte
37980 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  mpt..**.** {F163
37990 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  53} Calls to [sq
379a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
379b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
379c0 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67  loc()] that trig
379d0 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
379e0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75  attempts to redu
379f0 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20  ce memory usage 
37a00 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74  through the soft
37a10 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20   heap limit.**  
37a20 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73          mechanis
37a30 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20  m continue even 
37a40 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 74  if the attempt t
37a50 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a  o reduce memory.
37a60 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61 67  **          usag
37a70 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66 75  e is unsuccessfu
37a80 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34  l..**.** {F16354
37a90 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  } A negative or 
37aa0 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
37ab0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
37ac0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
37ad0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37ae0 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61  it(N)] means tha
37af0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
37b00 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ft.**          h
37b10 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73  eap limit and [s
37b20 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37b30 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
37b40 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ly be.**        
37b50 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65    called when me
37b60 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65  mory is complete
37b70 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  ly exhausted..**
37b80 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65  .** {F16355} The
37b90 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
37ba0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
37bb0 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
37bc0 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45  **.** {F16358} E
37bd0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
37be0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37bf0 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64  imit(N)] overrid
37c00 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
37c10 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62 79     values set by
37c20 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73   all prior calls
37c30 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
37c40 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37c50 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
37c60 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 63  API3REF:  Extrac
37c70 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
37c80 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
37c90 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a  able {F12850}.**
37ca0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
37cb0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61  .** returns meta
37cc0 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  -data about a sp
37cd0 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
37ce0 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
37cf0 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63  base.** table ac
37d00 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
37d10 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  he connection ha
37d20 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74  ndle passed as t
37d30 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
37d40 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a  n .** argument..
37d50 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e  **.** The column
37d60 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
37d70 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
37d80 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
37d90 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a  arameters to .**
37da0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
37db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
37dc0 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
37dd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
37de0 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
37df0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20   "main", "temp" 
37e00 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
37e10 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
37e20 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
37e30 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
37e40 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c  LL. If it is NUL
37e50 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
37e60 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
37e70 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
37e80 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
37e90 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
37ea0 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74  rithm as the dat
37eb0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65  abase engine use
37ec0 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65  s to .** resolve
37ed0 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
37ee0 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
37ef0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
37f00 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
37f10 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
37f20 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
37f30 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a  ble and column .
37f40 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
37f50 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
37f60 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
37f70 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
37f80 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79  rameters .** may
37f90 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
37fa0 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  Meta information
37fb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
37fc0 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
37fd0 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
37fe0 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
37ff0 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75   5th and subsequ
38000 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
38010 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
38020 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a   Any of these .*
38030 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  * arguments may 
38040 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  be NULL, in whic
38050 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
38060 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
38070 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66   of meta .** inf
38080 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 69 74  ormation is omit
38090 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ted..**.** <pre>
380a0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20  .** Parameter   
380b0 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20    Output Type   
380c0 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a     Description.*
380d0 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  * --------------
380e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
380f0 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74  -----.**.**   5t
38100 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
38110 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20  char*      Data 
38120 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20  type.**   6th   
38130 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
38140 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74  *      Name of t
38150 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  he default colla
38160 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a  tion sequence .*
38170 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20  *   7th         
38180 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
38190 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
381a0 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
381b0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
381c0 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69     8th         i
381d0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
381e0 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
381f0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
38200 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
38210 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69     9th         i
38220 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
38230 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
38240 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d  mn is AUTOINCREM
38250 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  ENT.** </pre>.**
38260 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
38270 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
38280 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
38290 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
382a0 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c  for the .** decl
382b0 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
382c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
382d0 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
382e0 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
382f0 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79   .** call to any
38300 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63   sqlite API func
38310 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tion..**.** If t
38320 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
38330 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
38340 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65   view, then an e
38350 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
38360 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
38370 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
38380 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
38390 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
383a0 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45  nd an .** INTEGE
383b0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f  R PRIMARY KEY co
383c0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
383d0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
383e0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
383f0 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ut .** parameter
38400 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
38410 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
38420 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
38430 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
38440 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
38450 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20  red IPK column, 
38460 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
38470 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
38480 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  et as .** follow
38490 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
384a0 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
384b0 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
384c0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
384d0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
384e0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
384f0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
38500 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
38510 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
38520 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
38530 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
38540 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
38550 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
38560 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
38570 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
38580 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
38590 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
385a0 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
385b0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
385c0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
385d0 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72  nd, an SQLITE er
385e0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
385f0 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
38600 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66  r message.** lef
38610 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  t in the databas
38620 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20  e handle (to be 
38630 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
38640 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
38650 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  )..**.** This AP
38660 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
38670 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
38680 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
38690 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
386a0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
386b0 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
386c0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
386d0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
386e0 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
386f0 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
38700 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
38710 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
38720 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
38730 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
38740 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
38750 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
38760 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
38770 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
38780 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
38790 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
387a0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
387b0 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
387c0 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
387d0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
387e0 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
387f0 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
38800 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
38810 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
38820 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
38830 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
38840 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
38850 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
38860 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38870 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
38880 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
38890 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
388a0 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
388b0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
388c0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
388d0 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
388e0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
388f0 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
38900 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
38910 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61  e if column is a
38920 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
38930 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
38940 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
38950 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a  ension {F12600}.
38960 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54  **.** {F12601} T
38970 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
38980 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
38990 72 66 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74  rface.** attempt